Build Your First Component

Overview

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

Set up a component project
Access checkout data
Handle user interactions
Deploy to production

Prerequisites

Ollie Shop CLI installed
Basic React knowledge
Access to a test store

Create the Component

Initialize Component

ollieshop component create --name free-shipping-bar --slot header
cd free-shipping-bar

Install Dependencies

npm install

Review Structure

free-shipping-bar/
├── src/
│   ├── index.tsx      # Component code
│   └── styles.css     # Styles
├── package.json       # Dependencies
└── meta.json         # Component metadata

Build the Component

Replace src/index.tsx:

index.tsx

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

export default function FreeShippingBar() {
  const { cart } = useCheckoutSession();
  const threshold = 10000; // $100 in cents
  const remaining = threshold - cart.total;
  const progress = Math.min((cart.total / threshold) * 100, 100);
  
  if (remaining <= 0) {
    return (
      <div className="shipping-bar success">
        <span>✓ Free shipping unlocked</span>
      </div>
    );
  }
  
  return (
    <div className="shipping-bar">
      <p>Add ${(remaining / 100).toFixed(2)} for free shipping</p>
      <div className="progress-track">
        <div 
          className="progress-fill" 
          style={{ width: `${progress}%` }}
        />
      </div>
    </div>
  );
}

Add Styles

Create src/styles.css:

styles.css

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

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

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

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

Test Locally

npm run dev

This opens a preview with:

Live component preview
Mock cart data controls
Mobile/desktop views

Deploy

Build

npm run build

Deploy

ollieshop component deploy

Verify

ollieshop component list

Using Checkout Data

The SDK provides hooks for accessing checkout data:

const { cart } = useCheckoutSession();

// Available properties
cart.items      // Array of cart items
cart.total      // Total in cents
cart.subtotal   // Subtotal before shipping/tax
cart.shipping   // Shipping cost
cart.tax        // Tax amount

Adding Interactivity

Components can modify the checkout:

const { addToCart, removeFromCart } = useCheckoutSession();

// Add item
await addToCart({
  id: 'product-123',
  quantity: 1
});

// Remove item
await removeFromCart('product-123');

Best Practices

Performance

// Memoize expensive calculations
const totalSavings = useMemo(() => {
  return cart.items.reduce((sum, item) => sum + item.discount, 0);
}, [cart.items]);

Error Handling

const [error, setError] = useState(null);

try {
  await addToCart(item);
} catch (err) {
  setError('Failed to add item');
}

Accessibility

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

Overview

Start Here

Core Concepts

Template Configuration

Customization

CLI Reference

Ollie SDK

Product updates

Build Your First Component

Overview

Prerequisites

Create the Component

Build the Component

Add Styles

Test Locally

Deploy

Using Checkout Data

Adding Interactivity

Best Practices

Performance

Error Handling

Accessibility

Next Steps

Component Examples

API Reference

Overview

Start Here

Core Concepts

Template Configuration

Customization

CLI Reference

Ollie SDK

Product updates

​Overview

​Prerequisites

​Create the Component

​Build the Component

​Add Styles

​Test Locally

​Deploy

​Using Checkout Data

​Adding Interactivity

​Best Practices

​Performance

​Error Handling

​Accessibility

​Next Steps

Component Examples

API Reference

Overview

Prerequisites

Create the Component

Build the Component

Add Styles

Test Locally

Deploy

Using Checkout Data

Adding Interactivity

Best Practices

Performance

Error Handling

Accessibility

Next Steps