Developer Quickstart

This tutorial guides you through the steps to create a new component, preview it while you develop, deploy it to your store, and assign it to a position (a slot, as we call it) in your checkout.

Prerequisites

macOS/Linux
Windows

Node.js 22+

node --version  # Should show v22.0.0 or higher

Download Node.js if not installed. The Ollie Shop CLI requires Node.js 22 or newer.

VS Code

Download VS Code - Recommended editor

Git

git --version  # Verify Git is installed

Ollie Shop Store

You have created a Store in Ollie Shop and you know its Store ID. It is the UUID in the Admin URL when you open the store: https://admin.ollie.shop/dashboard/store/<store-id>.

Ollie Shop CLI requires a Unix-like environment. Windows users must use WSL (Windows Subsystem for Linux).

Install WSL

Open PowerShell as Administrator and run:

wsl --install

Full WSL Installation Guide

Install Node.js 22 in WSL

Open WSL terminal and run:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

VS Code with WSL

Install VS Code
Install the WSL extension
Open WSL folders with: code . from WSL terminal

All commands in this guide must be run in the WSL terminal, not Windows Command Prompt or PowerShell.

Step 1: Create a Hello World Component

In your terminal, use the create-ollie-shop command to scaffold a new project with our Hello World component.

Create Your Project

Run the creation command

npx create-ollie-shop

You’ll be prompted for:

Project directory the folder to create. Defaults to my-checkout.
Store ID required. Paste the UUID of your store (see Prerequisites). The scaffold stops with Invalid store ID format if it is empty or not a UUID.
Version ID optional. Press Enter to skip; the CLI then works against the store’s default version.

You can also pass both as flags and skip the prompts: npx create-ollie-shop --store-id <uuid> --version-id <uuid>.A complete run looks like this:

🛍️  Create Ollie Shop

Project directory (my-checkout): my-checkout
Store ID: 7f3c9a1e-5b2d-4e8f-9a6c-1d2e3f4a5b6c
Version ID (optional, press Enter to skip):

📁 Creating Ollie Shop project "my-checkout"...
📄 Copying template files...
🧠 Installing Ollie skills...
🔧 Initializing git repository...

✅ Ollie Shop project created in my-checkout:
  $ cd my-checkout

Install dependencies:
  $ npm install

Start development:
  $ npm start

The scaffold downloads the Ollie Shop agent skill from GitHub, so it needs network access to github.com.

Navigate to Project

Replace [your-project-directory] with the directory you chose

cd [your-project-directory]

Meet your AI assistant

The project arrives with the Ollie Shop skill already installed, plus an AGENTS.md that points your coding agent at it. There is nothing to set up. Your assistant knows the CLI, the SDK hooks, and the slot catalog from your first prompt.Try it:

Prompt

Which slot should I put a free shipping banner in?

Step 2: Install Dependencies

After creating the project, set up your development environment.

Open in VS Code

code . # This opens your project in VS Code

Install Project Dependencies

Developing with Ollie Shop requires Node.js and npm.In the VS Code terminal, run:

npm install

This installs the Ollie Shop CLI and SDK as dev dependencies of your project, so you do not need a global install.

Step 3: Develop Your Component

Now let’s build a checkout component using the Ollie Shop SDK.

Open Component File

Open components/HelloWorld/index.tsx in VS Code.This file contains your component code that will be deployed to your checkout.

Add Checkout Features

Replace the code in the index.tsx file with the code below.You’ll now use the useCheckoutSession hook from the @ollie-shop/sdk package to access checkout session data.

index.tsx

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

export default function HelloWorld({ name = "Stranger" }: { name?: string }) {
  const { session } = useCheckoutSession();

  return (
    <div className={styles.container}>
      <h1>Hello, {name}!</h1>
      <p>Session ID: {session.id}</p>
      <p>Cart has {session.cartItems.length} items</p>
    </div>
  );
}

Your component now accesses real checkout session data!

Step 4: Preview Locally with Studio

Run the dev server and preview your component live in the checkout.

Start the Dev Server

In your VS Code terminal, start the dev server (hot reload):

npm start

This runs ollieshop start: it serves your components on http://localhost:4000, watches for changes, and opens Studio in your browser for your store.

Pass flags through npm when you need them: npm start -- --no-open keeps the browser closed, and npm start -- --browser-logs streams the checkout’s console output to your terminal.

Find your component in Studio

With the dev server running, HelloWorld appears in the Components tab of Studio and renders live in the checkout preview once it has a slot. Editing your code hot-reloads the preview automatically.The component is still unlinked: it has a temporary studio-HelloWorld id because nothing in your store knows about it yet.

Studio showing the local HelloWorld component — HelloWorld listed in the Components tab and rendered at the top of the cart

Step 5: Choose a Slot and Publish

Studio registers and deploys an unlinked component in one step.

Pick a slot

Open the HelloWorld card in the Components tab. In the Slot field, choose where the component renders (for example cart_header_full_page, above the cart content). The preview updates as soon as a slot is set.See Slots to understand what a slot is.

Publish

Click Publish. Studio creates the component in your store version, bundles your code, uploads it, and shows the build status. The button stays disabled until a slot is set.When the build succeeds, the CLI records the new component id in your project’s ollie.json under components, so the folder stays linked from now on.

View on your live store

Visit your store’s checkout to see your component live!

Prefer to register the component in the Admin first?

You can also create the component record yourself and link it to the folder before deploying.

In the Admin, open your store, click Components in the sidebar, then Create Component.
Fill in Name, Active, Slot, and Version, then click Create Component.
Copy the Component ID from the configuration page.

Link the folder in ollie.json:

ollie.json

{
  "storeId": "<your-store-id>",
  "components": {
    "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d": {
      "path": "components/HelloWorld",
      "slot": "cart_header_full_page"
    }
  }
}

Deploy from Studio (the card now shows a Deploy action) or from the terminal:

npx ollieshop deploy --component-id a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d --name HelloWorld --wait

Prefer the command line? The CLI is documented separately under CLI Reference.

You’ve successfully created and deployed your first Ollie Shop component! Your custom checkout enhancement is now live.

Next Steps

Integrate our skills into your project

Which coding agents pick the skill up on their own, how to install it where it’s missing, and how to keep it current

Build Your First Component

A deeper walkthrough: a free shipping progress bar, from folder to deploy

Overview

Start Here

AI Coding Agents

Core Concepts

Customization

Ollie Studio

Functions

CLI Reference

Ollie SDK

Analytics & Scripts

Tools & Tips

Product updates

Developer Quickstart

Prerequisites

Step 1: Create a Hello World Component

Step 2: Install Dependencies

Step 3: Develop Your Component

Step 4: Preview Locally with Studio

Step 5: Choose a Slot and Publish

Next Steps

Integrate our skills into your project

Build Your First Component

​Prerequisites

​Step 1: Create a Hello World Component

​Step 2: Install Dependencies

​Step 3: Develop Your Component

​Step 4: Preview Locally with Studio

​Step 5: Choose a Slot and Publish

​Next Steps

Integrate our skills into your project

Build Your First Component

Prerequisites

Step 1: Create a Hello World Component

Step 2: Install Dependencies

Step 3: Develop Your Component

Step 4: Preview Locally with Studio

Step 5: Choose a Slot and Publish

Next Steps