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

The Ollie Shop CLI installed (npm install -g @ollie-shop/cli) — see Installation
A scaffolded project (npx create-ollie-shop) — see the Quickstart
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 and a meta.json:

your-project/
├── components/
│   └── FreeShippingBar/
│       ├── index.tsx          # Component code (entry point)
│       ├── styles.module.css  # Styles (optional)
│       └── meta.json          # Component metadata (id, slot, props)
├── package.json               # Project dependencies
└── ...

Add meta.json

meta.json tells the tooling where the component goes. The slot is where it renders in the checkout (see Slots). Leave id out for local development — an unlinked component gets a temporary studio-* id until you register it.

meta.json

{
  "name": "Free Shipping Bar",
  "slot": "your-slot"
}

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

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:

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

Deploy

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

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

--wait polls until the build finishes.

Verify

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

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