Primeros pasos

Instalación

Arrancá con el storefront incluido y después usá la UI y el SDK como paquetes del workspace.

1. Conseguí el starter

Descargá el starter y verificalo contra su manifiesto SHA-256. Descomprimilo en un directorio nuevo y seguí su README. El monorepo y los starters generados recientemente incluyen packages/ui, packages/sdk y la app del storefront.

npm install
npm run build -w @notheadless/sdk
# En el starter exportado:
cp apps/store/.env.example apps/store/.env.local
npm run dev
# En cambio, en el monorepo de NotHeadless:
# cp apps/capi.tienda/.env.example apps/capi.tienda/.env.local
# npm run dev:store

Por ahora, la UI es un paquete de código fuente dentro del workspace. El SDK incluido mantiene el nombre @notheadless/sdk. No hace falta ningún registry privado de npm. Las versiones que ya descargaste pueden tener una estructura de carpetas más vieja; en ese caso, vale lo que diga el README que viene incluido.

2. Configurá la tienda

Completá los valores de runtime en el archivo de entorno local de tu storefront. El branding público se configura con las variables NEXT_PUBLIC_* del ejemplo.

.env.local

STOREFRONT_API_URL=https://storefront-api-poc.tiendanube.com/v2026-11
STOREFRONT_STORE_ID=YOUR_STORE_ID
STOREFRONT_TOKEN=YOUR_STOREFRONT_TOKEN
NEXT_PUBLIC_SITE_NAME=My store
NEXT_PUBLIC_SITE_URL=http://localhost:3000
# Restricción opcional que se aplica a las lecturas del catálogo Y al checkout:
CATALOG_CATEGORY_ID=

Mantené los tokens de storefront en el servidor. Nunca los pongas en variables NEXT_PUBLIC_*. Las previews de esta documentación usan datos de ejemplo y no necesitan estos valores.

3. Creá un cliente del lado del servidor

lib/nube.ts

import "server-only"
import { createClient } from "@notheadless/sdk"

export function getNube() {
  return createClient({
    baseUrl: process.env.STOREFRONT_API_URL,
    storeId: process.env.STOREFRONT_STORE_ID!,
    token: process.env.STOREFRONT_TOKEN,
    fetchOptions: { cache: "no-store" },
  })
}

Creá el cliente durante el request, así el build no depende de credenciales reales de la tienda. Mirá las opciones del cliente y los handlers de carrito y checkout.

4. Conectá la UI compartida

Agregá a tu app las dependencias hermanas del workspace:

package.json · dependencies

{
  "@notheadless/ui": "*",
  "@notheadless/sdk": "*"
}

next.config.ts

const config = {
  transpilePackages: ["@notheadless/ui", "@notheadless/sdk"],
}
export default config

app/globals.css

@import "tailwindcss";
@import "@notheadless/ui/styles.css";

El starter ya incluye Tailwind v4, las variables del tema, los estilos de animación y los endpoints del servidor. Si lo integrás en otra app, copiá la configuración del tema desde la demo.

components/store-providers.tsx

"use client"

import { StoreProvider, CartSheet } from "@notheadless/ui"
import { Toaster } from "@notheadless/ui/primitives/sonner"

export function StoreProviders({ children }: { children: React.ReactNode }) {
  return (
    <StoreProvider currency="ARS" locale="es-AR">
      {children}
      <CartSheet />
      <Toaster />
    </StoreProvider>
  )
}

Renderizá StoreProviders envolviendo el contenido de tu app, dentro del body del root layout.
Habilitá los hosts de las imágenes de tus productos en next.config.ts, o configurá explícitamente imágenes sin optimizar.
Exponé /api/cart y /api/checkout con los handlers de servidor del SDK.

Opcional: registry de código fuente

El paquete de UI también genera un registry de código fuente con 28 ítems. Desde la raíz del monorepo, corré npm run build:ui. Configurá REGISTRY_URL con el origen de tu registry y después publicá packages/ui/registry-assets en /r/. Quien consuma el registry también necesita tener el SDK disponible. Este sitio de documentación no publica un endpoint de registry.

Cargando documentación…