Build Your First Component

Overview

This guide walks through building a free shipping progress bar component. You’ll learn how to:

Create a component in your project
Access checkout data with the SDK
Run it locally
Register and deploy it to your store

Let your agent build it. The Ollie Shop skill ships with projects created by npx create-ollie-shop, and it carries an opinionated recipe for this exact component.

Prompt

Create a free shipping progress bar component.

It covers the rest of this guide too, one step at a time:

Access checkout data with the SDK: Which session fields do I need for a free shipping bar?
Run it locally: Start the dev server and show me the component in Studio.
Register and deploy it: Register this component in my store and deploy it.

Working through the walkthrough below teaches you what the agent is doing, which is worth doing once. After that, the prompts are faster.Don’t have the skill yet? Install it.

Prerequisites

A scaffolded project (npx create-ollie-shop), see the Quickstart. It installs the Ollie Shop CLI as a dev dependency, so npx ollieshop ... works from the project root. A global install (see Installation) is optional.
Basic React knowledge
Access to a store

A component is a folder under components/ in your project. It is not a standalone package: ollieshop component create only registers metadata in the database; it does not scaffold a folder. The actual code lives in your project.

Create the Component

Create the folder

Inside your project, create components/FreeShippingBar/ with an index.tsx:

your-project/
├── components/
│   └── FreeShippingBar/
│       ├── index.tsx          # Component code (entry point)
│       └── styles.module.css  # Styles (optional)
├── ollie.json                 # Store id + the components map
├── package.json               # Project dependencies
└── ...

Declare it in ollie.json

The components map in ollie.json tells the tooling which folders are components and where each one renders. The key is a local alias, path is the folder, and slot is the slot id in the checkout (see Slots). cart_header_full_page renders above the cart content and is empty by default, which makes it a good first slot.

ollie.json

{
  "storeId": "<your-store-id>",
  "components": {
    "FreeShippingBar": {
      "path": "components/FreeShippingBar",
      "slot": "cart_header_full_page"
    }
  }
}

There is no id yet, so the component is unlinked: the dev server gives it a temporary studio-FreeShippingBar id until you register it. A folder under components/ with no entry in the map is still discovered, but without a slot it is built and not placed anywhere in the checkout.

Older projects used a meta.json file inside each component folder. The CLI still reads it as a fallback, and npx ollieshop setup migrates those files into the ollie.json map.

Build the Component

Create components/FreeShippingBar/index.tsx:

index.tsx

import React from 'react';
import { useCheckoutSession } from '@ollie-shop/sdk';
import styles from './styles.module.css';

export default function FreeShippingBar() {
  const { session } = useCheckoutSession();
  const { totals, locale } = session;

  const threshold = 10000; // $100 in cents
  const subtotal = totals.items;
  const remaining = threshold - subtotal;
  const progress = Math.min((subtotal / threshold) * 100, 100);

  const format = (cents: number) =>
    new Intl.NumberFormat(locale.language, {
      style: 'currency',
      currency: locale.currency,
    }).format(cents / 100);

  if (remaining <= 0) {
    return (
      <div className={`${styles.shippingBar} ${styles.success}`} role="status" aria-live="polite">
        <span>✓ Free shipping unlocked</span>
      </div>
    );
  }

  return (
    <div className={styles.shippingBar} role="status" aria-live="polite">
      <p>Add {format(remaining)} for free shipping</p>
      <div className={styles.progressTrack}>
        <div className={styles.progressFill} style={{ width: `${progress}%` }} />
      </div>
    </div>
  );
}

Add Styles

Create components/FreeShippingBar/styles.module.css:

styles.module.css

.shippingBar {
  background: #f3f4f6;
  padding: 12px;
  text-align: center;
  font-size: 14px;
}

.success {
  background: #10b981;
  color: white;
}

.progressTrack {
  background: #e5e7eb;
  height: 6px;
  border-radius: 3px;
  margin-top: 8px;
  overflow: hidden;
}

.progressFill {
  background: #3b82f6;
  height: 100%;
  transition: width 0.3s ease;
}

Test Locally

Start the local dev server from your project root:

npm start
# or, directly:
ollieshop start

This discovers your components, opens Ollie Studio in the browser, and hot-reloads as you edit.

Register & Deploy

The quickest route is Studio: open the component’s card, confirm the slot, and click Publish. Studio creates the component record, deploys the build, and writes the new id into ollie.json for you. The steps below do the same thing from the terminal.

Create the component record in a store version to get its component id. You can do this in the admin dashboard, or via the CLI:

npx ollieshop component create \
  --version-id <version-uuid> \
  --name "Free Shipping Bar" \
  --slot cart_header_full_page

Link the folder to the id

component create does not touch your project files. Replace the alias in ollie.json with the id it returned, so the folder is linked from now on:

ollie.json

{
  "storeId": "<your-store-id>",
  "components": {
    "<component-uuid>": {
      "path": "components/FreeShippingBar",
      "slot": "cart_header_full_page"
    }
  }
}

Deploy

Deploy bundles the local components/FreeShippingBar folder and uploads it to the builder. Pass the component id and the folder name:

npx ollieshop deploy \
  --component-id <component-uuid> \
  --name FreeShippingBar \
  --wait

--wait polls until the build finishes.

Verify

npx ollieshop component list --store-id <store-uuid>

Using Checkout Data

The SDK exposes hooks for reading checkout data. useCheckoutSession returns the parsed session:

const { session } = useCheckoutSession();

session.cartItems        // Array of cart items
session.totals.items     // Subtotal of items, in cents
session.totals.shipping  // Shipping cost, in cents (optional)
session.totals.total     // Grand total, in cents
session.locale           // { currency, language, country }
session.customer         // Customer data (optional)

See the hooks reference and the CheckoutSession type for the full shape.

Adding Interactivity

Cart changes go through useCheckoutAction, not useCheckoutSession:

import { useCheckoutAction } from '@ollie-shop/sdk';

function RemoveFirstItemButton() {
  const { execute, isPending } = useCheckoutAction('REMOVE_ITEMS', {
    onError: ({ serverError }) =>
      console.error('Failed to remove item', serverError?.message),
  });

  return (
    <button onClick={() => execute([0])} disabled={isPending}>
      Remove first item
    </button>
  );
}

Best Practices

Performance

// Memoize expensive calculations derived from the session
const totalSavings = useMemo(
  () =>
    session.cartItems.reduce(
      (sum, item) => sum + (item.originalPrice - item.price) * item.quantity,
      0,
    ),
  [session.cartItems],
);

Error Handling

Surface failures to the user via useMessages:

const { addMessage } = useMessages();
const { execute } = useCheckoutAction('ADD_ITEMS', {
  onError: ({ serverError }) => addMessage({ type: 'error', error: serverError }),
});

Accessibility

<div role="status" aria-live="polite">
  {remaining > 0
    ? `${format(remaining)} until free shipping`
    : 'Free shipping unlocked'}
</div>

Overview

Start Here

AI Coding Agents

Core Concepts

Customization

Ollie Studio

Functions

CLI Reference

Ollie SDK

Analytics & Scripts

Tools & Tips

Product updates

Build Your First Component

Overview

Prerequisites

Create the Component

Build the Component

Add Styles

Test Locally

Register & Deploy

Using Checkout Data

Adding Interactivity

Best Practices

Performance

Error Handling

Accessibility

Next Steps

Custom Component 101

API Reference

​Overview

​Prerequisites

​Create the Component

​Build the Component

​Add Styles

​Test Locally

​Register & Deploy

​Using Checkout Data

​Adding Interactivity

​Best Practices

​Performance

​Error Handling

​Accessibility

​Next Steps

Custom Component 101

API Reference

Overview

Prerequisites

Create the Component

Build the Component

Add Styles

Test Locally

Register & Deploy

Using Checkout Data

Adding Interactivity

Best Practices

Performance

Error Handling

Accessibility

Next Steps