Developer Quickstart

This tutorial will guide your through the necessary steps to create a new component, preview it while in development, deploy it to your store and assign it to a specific position (or slot as we call it) in your store.

Prerequisites

macOS/Linux
Windows

Node.js 20+

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

Download Node.js if not installed

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

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 in WSL

Open WSL terminal and run:

curl -fsSL https://deb.nodesource.com/setup_18.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 triger the scaffolding of 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 Name which will be the name on the folder.
Store ID leave empty - you’ll be able to add this information at a later step.
VTEX Account Name the id of your store in in your ecommerce provider.
Version ID leave empty - you’ll be able to add this information at a later step

Navigate to Project

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

cd [your-project-name]

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 all required packages for your project.

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 React from 'react';
import styles from './helloWorld.module.css';

export default function HelloWorld({ name = "Stranger" }) {
  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: Create Component in Admin Dashboard

Before deploying, you need to register your component in the admin dashboard.

Navigate to Components

In the admin dashboard:

Click “Components” in the sidebar
Click “Create Component” or “Create Your First Component”

Configure Component

Fill in the component details:

Name: Your component name (e.g., “My Custom Component”)
Active: Toggle ON to enable the component
Slot: Select where the component appears (e.g., “Cart Sidebar”)
Version: Select your store version

Click “Create Component”

Get Component ID

After creation, you’ll see the Component Configuration page.Copy the Component ID - you’ll need this for deployment!Example: 26f2e95f-e7f3-4e26-903f-a5ad4e03f584

Step 5: 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 Ollie CLI dev server (hot reload):

ollieshop start

This serves your components on http://localhost:4000 and watches for changes.

Open Studio

In the admin dashboard, go to Studio. With the dev server running, your component appears in the Components tab and renders live in the checkout preview. Editing your code hot-reloads the preview automatically.

Note Your Component ID

From Step 4, keep the Component ID handy — you’ll use it to deploy: 26f2e95f-e7f3-4e26-903f-a5ad4e03f584

Step 6: Deploy with Studio

With the dev server running (Step 5) and your component visible in Studio, deploy it without leaving the dashboard.

Open the Components tab

In Studio, find your component in the Components tab. Make sure the CLI status dot is green (the dev server is connected) and the build has no errors.

Deploy

Click the upload icon on your component’s card. Confirm in the dialog — Studio bundles your component, uploads it, and shows the build status.

Wait for the build to succeed

Studio polls the build and notifies you when it’s done.

View on your live store

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

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.

Overview

Start Here

Core Concepts

Customization

CLI Reference

Ollie SDK

Analytics & Scripts

AI Skills

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: Create Component in Admin Dashboard

Step 5: Preview Locally with Studio

Step 6: Deploy with Studio

​Prerequisites

​Step 1: Create a Hello World Component

​Step 2: Install Dependencies

​Step 3: Develop Your Component

​Step 4: Create Component in Admin Dashboard

​Step 5: Preview Locally with Studio

​Step 6: Deploy with Studio

Prerequisites

Step 1: Create a Hello World Component

Step 2: Install Dependencies

Step 3: Develop Your Component

Step 4: Create Component in Admin Dashboard

Step 5: Preview Locally with Studio

Step 6: Deploy with Studio