Storefront Kit

The Vantemo Storefront Kit is a set of React hooks, server utilities, and components for building headless storefronts with Next.js. It handles API communication, cart state management, and checkout flows so you can focus on your UI.

Installation

npm

npm install @vantemo/storefront-kit

pnpm

pnpm add @vantemo/storefront-kit

Setup

1. Configure Environment Variables

.env.local

# Your shop's API URL
NEXT_PUBLIC_VANTEMO_API_URL=https://your-shop.vantemo.com

# Publishable key for client-side requests (safe to expose)
NEXT_PUBLIC_VANTEMO_PUBLISHABLE_KEY=vt_pk_live_...

# Secret key for server-side requests (never expose to browser)
VANTEMO_SECRET_KEY=vt_sk_live_...

2. Create the API Client

lib/vantemo.ts

import { createStorefrontClient } from '@vantemo/storefront-kit';

// Server-side client — uses secret key for full access
export const vantemo = createStorefrontClient({
  apiUrl: process.env.NEXT_PUBLIC_VANTEMO_API_URL!,
  apiKey: process.env.VANTEMO_SECRET_KEY!,
});

// Client-side client — uses publishable key (read-only)
export const vantemoPublic = createStorefrontClient({
  apiUrl: process.env.NEXT_PUBLIC_VANTEMO_API_URL!,
  apiKey: process.env.NEXT_PUBLIC_VANTEMO_PUBLISHABLE_KEY!,
});

3. Fetch Products (Server Component)

app/products/page.tsx

import { vantemo } from '@/lib/vantemo';

export default async function ProductsPage() {
  const { data: products } = await vantemo.products.list();

  return (
    <div className="grid grid-cols-3 gap-6">
      {products.map((product) => (
        <div key={product.id}>
          <h2>{product.title}</h2>
          <p>€{(product.price / 100).toFixed(2)}</p>
        </div>
      ))}
    </div>
  );
}

4. Cart Management (Client Component)

components/AddToCartButton.tsx

'use client';

import { useCart } from '@vantemo/storefront-kit/react';

export function AddToCartButton({ productId }: { productId: string }) {
  const { addItem, isLoading } = useCart();

  return (
    <button
      onClick={() => addItem({ productId, quantity: 1 })}
      disabled={isLoading}
    >
      {isLoading ? 'Adding...' : 'Add to Cart'}
    </button>
  );
}

API Methods

The storefront client provides methods for all public API endpoints:

Method	Description
`products.list()`	List products with filtering and pagination
`products.get(id)`	Get a single product by ID
`cart.get()`	Get the current cart
`cart.addItem(item)`	Add an item to the cart
`cart.updateItem(id, quantity)`	Update item quantity
`cart.removeItem(id)`	Remove an item from the cart
`checkout.create(cartId)`	Create a checkout session
`checkout.complete(sessionId)`	Complete the checkout

Next Steps

API Reference — Full endpoint documentation
Authentication — API key types and scopes
Webhooks — Subscribe to order events

Storefront Kit

On this page