@vitrine-kit/vitrine 0.3.0 → 0.4.0

package/kit/templates/backend-payload/files/payload.config.ts

@@ -0,0 +1,32 @@
+// The client's Payload 3 config. Collections are assembled by the blueprint (base +
+// additive feature extensions, lib/blueprint.ts — generated by the CLI). The DB is
+// chosen zero-config (db.ts → §18.1). onInit runs the demo seed and dev admin (dev only).
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildConfig } from 'payload';
+import type { CollectionConfig } from 'payload';
+import { lexicalEditor } from '@payloadcms/richtext-lexical';
+import sharp from 'sharp';
+import { collections } from './lib/blueprint.js';
+import { resolveDbAdapter } from './lib/adapter/db.js';
+import { seedDemo } from './lib/seed/run.js';
+import { ensureDevAdmin } from './lib/seed/admin.js';
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default buildConfig({
+  admin: {
+    user: 'users',
+    importMap: { baseDir: path.resolve(dirname) },
+  },
+  collections: collections as unknown as CollectionConfig[],
+  editor: lexicalEditor(),
+  secret: process.env.PAYLOAD_SECRET ?? 'dev-secret-change-me',
+  db: await resolveDbAdapter(),
+  sharp,
+  typescript: { outputFile: path.resolve(dirname, 'payload-types.ts') },
+  async onInit(payload) {
+    await seedDemo(payload);
+    await ensureDevAdmin(payload);
+  },
+});

package/kit/templates/backend-payload/files/seed-assets/placeholder-1.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="600" viewBox="0 0 600 600" role="img" aria-label="Classic T-Shirt">
+  <rect width="600" height="600" fill="#e7e5e4"/>
+  <rect x="40" y="40" width="520" height="520" rx="16" fill="#d6d3d1"/>
+  <text x="300" y="312" font-family="system-ui, sans-serif" font-size="40" fill="#57534e" text-anchor="middle">T-Shirt</text>
+</svg>

package/kit/templates/backend-payload/files/seed-assets/placeholder-2.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="600" viewBox="0 0 600 600" role="img" aria-label="Zip Hoodie">
+  <rect width="600" height="600" fill="#e0e7ff"/>
+  <rect x="40" y="40" width="520" height="520" rx="16" fill="#c7d2fe"/>
+  <text x="300" y="312" font-family="system-ui, sans-serif" font-size="48" fill="#4338ca" text-anchor="middle">Hoodie</text>
+</svg>

package/kit/templates/backend-payload/files/seed-assets/placeholder-3.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="600" viewBox="0 0 600 600" role="img" aria-label="Logo Cap">
+  <rect width="600" height="600" fill="#dcfce7"/>
+  <rect x="40" y="40" width="520" height="520" rx="16" fill="#bbf7d0"/>
+  <text x="300" y="312" font-family="system-ui, sans-serif" font-size="48" fill="#15803d" text-anchor="middle">Cap</text>
+</svg>

package/kit/templates/backend-payload/files/seed-assets/placeholder-4.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="600" viewBox="0 0 600 600" role="img" aria-label="Tote Bag">
+  <rect width="600" height="600" fill="#fef3c7"/>
+  <rect x="40" y="40" width="520" height="520" rx="16" fill="#fde68a"/>
+  <text x="300" y="312" font-family="system-ui, sans-serif" font-size="44" fill="#b45309" text-anchor="middle">Tote</text>
+</svg>

package/kit/templates/backend-payload/files/seed-assets/placeholder-5.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="600" viewBox="0 0 600 600" role="img" aria-label="Socks, 3 Pairs">
+  <rect width="600" height="600" fill="#fae8ff"/>
+  <rect x="40" y="40" width="520" height="520" rx="16" fill="#f5d0fe"/>
+  <text x="300" y="312" font-family="system-ui, sans-serif" font-size="48" fill="#a21caf" text-anchor="middle">Socks</text>
+</svg>

package/kit/templates/backend-vendure/files/.dockerignore

@@ -0,0 +1,8 @@
+node_modules
+.next
+.git
+.vitrine
+.env
+.env.local
+static/assets
+**/*.tsbuildinfo

package/kit/templates/backend-vendure/files/Dockerfile

@@ -0,0 +1,24 @@
+# syntax=docker/dockerfile:1
+# Vitrine client image on Vendure. One image, two commands (compose): the Vendure server
+# (`node dist/index.js`) and the Next storefront (`next start`). Target — VPS.
+FROM node:20-alpine AS base
+RUN corepack enable && corepack prepare pnpm@9.15.0 --activate
+WORKDIR /app
+
+FROM base AS deps
+COPY package.json pnpm-lock.yaml* ./
+RUN pnpm install --frozen-lockfile || pnpm install
+
+FROM base AS build
+ENV NEXT_TELEMETRY_DISABLED=1
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN pnpm build
+
+FROM base AS runtime
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --from=build /app ./
+EXPOSE 3000 3001
+# The command is overridden in docker-compose (web / server).
+CMD ["pnpm", "start"]

package/kit/templates/backend-vendure/files/docker-compose.yml

@@ -0,0 +1,50 @@
+# Reference Vitrine deployment on Vendure: db (Postgres) + server (Vendure) + web (Next).
+# Run: VENDURE_SUPERADMIN_PASSWORD=... docker compose up --build
+services:
+  db:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: vitrine
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-vitrine}
+      POSTGRES_DB: vitrine
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U vitrine']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  server:
+    build:
+      context: .
+    restart: unless-stopped
+    command: ['node', 'dist/index.js']
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: postgres://vitrine:${POSTGRES_PASSWORD:-vitrine}@db:5432/vitrine
+      VENDURE_SUPERADMIN_USERNAME: ${VENDURE_SUPERADMIN_USERNAME:-superadmin}
+      VENDURE_SUPERADMIN_PASSWORD: ${VENDURE_SUPERADMIN_PASSWORD:?set VENDURE_SUPERADMIN_PASSWORD}
+    ports:
+      - '3001:3001'
+    depends_on:
+      db:
+        condition: service_healthy
+
+  web:
+    build:
+      context: .
+    restart: unless-stopped
+    command: ['pnpm', 'start']
+    environment:
+      NODE_ENV: production
+      VENDURE_SHOP_API_URL: http://server:3001/shop-api
+      NEXT_PUBLIC_SITE_URL: ${NEXT_PUBLIC_SITE_URL:-http://localhost:3000}
+    ports:
+      - '3000:3000'
+    depends_on:
+      - server
+
+volumes:
+  pgdata:

package/kit/templates/backend-vendure/files/lib/adapter/graphql.ts

@@ -0,0 +1,27 @@
+// Thin Vendure Shop API client (GraphQL over fetch, no dependencies). The active
+// order's session uses a bearer token (vendure-auth-token). Next glue.
+const SHOP_API = process.env.VENDURE_SHOP_API_URL ?? 'http://localhost:3001/shop-api';
+
+export interface ShopResult<T> {
+  data: T;
+  token?: string;
+}
+
+export async function shopQuery<T>(
+  query: string,
+  variables: Record<string, unknown> = {},
+  token?: string,
+): Promise<ShopResult<T>> {
+  const res = await fetch(SHOP_API, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+    },
+    body: JSON.stringify({ query, variables }),
+  });
+  const nextToken = res.headers.get('vendure-auth-token') ?? token ?? undefined;
+  const json = (await res.json()) as { data: T; errors?: unknown[] };
+  if (json.errors) throw new Error(`[vitrine] Vendure GraphQL: ${JSON.stringify(json.errors)}`);
+  return { data: json.data, token: nextToken };
+}

package/kit/templates/backend-vendure/files/lib/adapter/index.ts

@@ -0,0 +1,20 @@
+// Resolver for the active backend (Vendure). The same interface as backend-payload —
+// so the storefront (app/(frontend)) and the catalog/cart features don't change.
+import type { CatalogSource, CommerceBackend } from '@vitrine-kit/contracts';
+import { VendureCatalogSource } from './vendure-catalog.js';
+import { VendureCommerceBackend } from './vendure-commerce.js';
+
+let catalog: CatalogSource | null = null;
+let commerce: CommerceBackend | null = null;
+
+export async function getCatalogSource(): Promise<CatalogSource> {
+  if (!catalog) catalog = new VendureCatalogSource();
+  return catalog;
+}
+
+export async function getCommerceBackend(): Promise<CommerceBackend> {
+  if (!commerce) {
+    commerce = new VendureCommerceBackend(process.env.NEXT_PUBLIC_SITE_URL ?? 'http://localhost:3000');
+  }
+  return commerce;
+}

package/kit/templates/backend-vendure/files/lib/adapter/map.ts

@@ -0,0 +1,107 @@
+// Pure mappers from Vendure Shop API → contract types. They depend only on
+// @vitrine-kit/contracts and local structural types. This is the proof of
+// portability: the same Product/Category/Cart/Order types the Payload adapter returns
+// — meaning the catalog/cart features work on Vendure WITHOUT changes.
+import type { Cart, Category, Money, Order, OrderStatus, Product, Variant } from '@vitrine-kit/contracts';
+import type { VAsset, VCollection, VOrder, VProduct, VVariant } from './vendure-types.js';
+
+const asId = (v: string | number): string => String(v);
+
+export function mapVendureCollection(c: VCollection): Category {
+  return {
+    id: asId(c.id),
+    slug: c.slug,
+    title: c.name,
+    description: c.description ?? undefined,
+    parentId: c.parent ? asId(c.parent.id) : null,
+  };
+}
+
+function mapVariant(v: VVariant): Variant {
+  return {
+    id: asId(v.id),
+    sku: v.sku,
+    title: v.name ?? undefined,
+    price: v.priceWithTax as Money,
+    currency: v.currencyCode,
+    stock: null, // the Shop API returns stockLevel as a string — we don't track numeric stock here
+  };
+}
+
+export function mapVendureProduct(p: VProduct): Product {
+  const variants = p.variants.map(mapVariant);
+  const assets = [p.featuredAsset, ...(p.assets ?? [])].filter((a): a is VAsset => a != null);
+  const images = assets.map((a) => ({ url: a.preview, width: a.width ?? undefined, height: a.height ?? undefined }));
+  const prices = variants.map((v) => v.price);
+  const currency = variants[0]?.currency ?? 'USD';
+
+  return {
+    id: asId(p.id),
+    slug: p.slug,
+    title: p.name,
+    description: p.description ?? undefined,
+    categoryIds: (p.collections ?? []).map((c) => asId(c.id)),
+    images,
+    variants,
+    priceRange: prices.length > 0 ? { min: Math.min(...prices), max: Math.max(...prices), currency } : undefined,
+  };
+}
+
+/** Vendure order state → contract OrderStatus. */
+export function mapOrderState(state: string): OrderStatus {
+  switch (state) {
+    case 'PaymentSettled':
+    case 'PaymentAuthorized':
+      return 'paid';
+    case 'Shipped':
+    case 'Delivered':
+    case 'Fulfilled':
+      return 'fulfilled';
+    case 'Cancelled':
+      return 'cancelled';
+    default:
+      return 'pending';
+  }
+}
+
+/** Active Vendure order → Cart (the same the cart feature gets on Payload). */
+export function mapVendureOrderToCart(o: VOrder): Cart {
+  return {
+    id: o.code,
+    currency: o.currencyCode,
+    subtotal: o.subTotalWithTax,
+    total: o.totalWithTax,
+    lines: o.lines.map((l) => ({
+      id: asId(l.id),
+      variantId: asId(l.productVariant.id),
+      productId: l.productVariant.product ? asId(l.productVariant.product.id) : '',
+      title: l.productVariant.name,
+      quantity: l.quantity,
+      unitPrice: l.unitPriceWithTax,
+      lineTotal: l.linePriceWithTax,
+      image: l.featuredAsset?.preview,
+    })),
+  };
+}
+
+export function mapVendureOrder(o: VOrder): Order {
+  const cart = mapVendureOrderToCart(o);
+  return {
+    id: asId(o.id),
+    number: o.code,
+    status: mapOrderState(o.state),
+    lines: cart.lines.map((l) => ({
+      variantId: l.variantId,
+      productId: l.productId,
+      title: l.title,
+      quantity: l.quantity,
+      unitPrice: l.unitPrice,
+      lineTotal: l.lineTotal,
+    })),
+    currency: o.currencyCode,
+    subtotal: o.subTotalWithTax,
+    total: o.totalWithTax,
+    email: o.customer?.emailAddress ?? undefined,
+    createdAt: o.createdAt ?? new Date().toISOString(),
+  };
+}

package/kit/templates/backend-vendure/files/lib/adapter/vendure-catalog.ts

@@ -0,0 +1,62 @@
+// CatalogSource contract implementation on top of the Vendure Shop API. Normalization
+// lives in the pure mappers (map.ts). The same contract as the Payload adapter → the
+// catalog features are portable without changes.
+import type { CatalogSource, Category, Product, ProductQuery } from '@vitrine-kit/contracts';
+import { shopQuery } from './graphql.js';
+import { mapVendureCollection, mapVendureProduct } from './map.js';
+import type { VCollection, VProduct } from './vendure-types.js';
+
+const PRODUCT_FIELDS = `
+  id name slug description
+  featuredAsset { preview width height }
+  assets { preview }
+  collections { id slug name }
+  variants { id sku name priceWithTax currencyCode stockLevel }
+`;
+
+export class VendureCatalogSource implements CatalogSource {
+  async listProducts(query: ProductQuery = {}): Promise<Product[]> {
+    const take = query.perPage ?? 24;
+    const skip = ((query.page ?? 1) - 1) * take;
+
+    if (query.category) {
+      const { data } = await shopQuery<{ collection: { productVariants: { items: { product: VProduct }[] } } | null }>(
+        `query ($slug: String!) { collection(slug: $slug) { productVariants { items { product { ${PRODUCT_FIELDS} } } } } }`,
+        { slug: query.category },
+      );
+      const byId = new Map<string, VProduct>();
+      for (const it of data.collection?.productVariants.items ?? []) byId.set(String(it.product.id), it.product);
+      return [...byId.values()].map(mapVendureProduct);
+    }
+
+    const { data } = await shopQuery<{ products: { items: VProduct[] } }>(
+      `query ($take: Int, $skip: Int) { products(options: { take: $take, skip: $skip }) { items { ${PRODUCT_FIELDS} } } }`,
+      { take, skip },
+    );
+    return data.products.items.map(mapVendureProduct);
+  }
+
+  async getProduct(slug: string): Promise<Product | null> {
+    const { data } = await shopQuery<{ product: VProduct | null }>(
+      `query ($slug: String!) { product(slug: $slug) { ${PRODUCT_FIELDS} } }`,
+      { slug },
+    );
+    return data.product ? mapVendureProduct(data.product) : null;
+  }
+
+  async listCategories(): Promise<Category[]> {
+    const { data } = await shopQuery<{ collections: { items: VCollection[] } }>(
+      `{ collections { items { id slug name description parent { id } } } }`,
+    );
+    return data.collections.items.map(mapVendureCollection);
+  }
+
+  async search(term: string): Promise<Product[]> {
+    const { data } = await shopQuery<{ search: { items: { slug: string }[] } }>(
+      `query ($term: String!) { search(input: { term: $term, groupByProduct: true }) { items { slug } } }`,
+      { term },
+    );
+    const products = await Promise.all(data.search.items.map((i) => this.getProduct(i.slug)));
+    return products.filter((p): p is Product => p !== null);
+  }
+}

package/kit/templates/backend-vendure/files/lib/adapter/vendure-commerce.ts

@@ -0,0 +1,76 @@
+// CommerceBackend contract implementation on top of Vendure (active order + session
+// token). cartId == the Vendure session auth-token. Money totals come from Vendure;
+// normalization lives in map.ts. Payment — Vendure's Stripe plugin (startCheckout moves
+// the order to ArrangingPayment). Next glue, validated against a running Vendure.
+import type { Cart, CommerceBackend, Order } from '@vitrine-kit/contracts';
+import { shopQuery } from './graphql.js';
+import { mapVendureOrder, mapVendureOrderToCart } from './map.js';
+import type { VOrder } from './vendure-types.js';
+
+const ORDER_FIELDS = `
+  id code state currencyCode subTotalWithTax totalWithTax createdAt
+  customer { emailAddress }
+  lines {
+    id quantity unitPriceWithTax linePriceWithTax
+    featuredAsset { preview }
+    productVariant { id sku name product { id slug } }
+  }
+`;
+
+const emptyCart = (id: string): Cart => ({ id, lines: [], currency: 'USD', subtotal: 0, total: 0 });
+
+export class VendureCommerceBackend implements CommerceBackend {
+  constructor(private readonly baseUrl: string) {}
+
+  async createCart(): Promise<Cart> {
+    // Vendure issues a session token on any request; the active order is created on addItem.
+    const { token } = await shopQuery(`{ activeChannel { id } }`);
+    return emptyCart(token ?? '');
+  }
+
+  async getCart(cartId: string): Promise<Cart | null> {
+    const { data } = await shopQuery<{ activeOrder: VOrder | null }>(`{ activeOrder { ${ORDER_FIELDS} } }`, {}, cartId);
+    return data.activeOrder ? mapVendureOrderToCart(data.activeOrder) : emptyCart(cartId);
+  }
+
+  async addItem(cartId: string, variantId: string, qty: number): Promise<Cart> {
+    const { data } = await shopQuery<{ addItemToOrder: VOrder }>(
+      `mutation ($id: ID!, $q: Int!) { addItemToOrder(productVariantId: $id, quantity: $q) { ...on Order { ${ORDER_FIELDS} } } }`,
+      { id: variantId, q: qty },
+      cartId,
+    );
+    return mapVendureOrderToCart(data.addItemToOrder);
+  }
+
+  async updateItem(cartId: string, lineId: string, qty: number): Promise<Cart> {
+    const { data } = await shopQuery<{ adjustOrderLine: VOrder }>(
+      `mutation ($id: ID!, $q: Int!) { adjustOrderLine(orderLineId: $id, quantity: $q) { ...on Order { ${ORDER_FIELDS} } } }`,
+      { id: lineId, q: qty },
+      cartId,
+    );
+    return mapVendureOrderToCart(data.adjustOrderLine);
+  }
+
+  async removeItem(cartId: string, lineId: string): Promise<Cart> {
+    const { data } = await shopQuery<{ removeOrderLine: VOrder }>(
+      `mutation ($id: ID!) { removeOrderLine(orderLineId: $id) { ...on Order { ${ORDER_FIELDS} } } }`,
+      { id: lineId },
+      cartId,
+    );
+    return mapVendureOrderToCart(data.removeOrderLine);
+  }
+
+  async startCheckout(cartId: string): Promise<{ redirectUrl: string }> {
+    // Transition to payment; Vendure's Stripe plugin creates a PaymentIntent on the payment page.
+    await shopQuery(`mutation { transitionOrderToState(state: "ArrangingPayment") { ...on Order { id } } }`, {}, cartId);
+    return { redirectUrl: `${this.baseUrl}/checkout/payment` };
+  }
+
+  async getOrder(id: string): Promise<Order | null> {
+    const { data } = await shopQuery<{ orderByCode: VOrder | null }>(
+      `query ($code: String!) { orderByCode(code: $code) { ${ORDER_FIELDS} } }`,
+      { code: id },
+    );
+    return data.orderByCode ? mapVendureOrder(data.orderByCode) : null;
+  }
+}

package/kit/templates/backend-vendure/files/lib/adapter/vendure-types.ts

@@ -0,0 +1,61 @@
+// Structural shapes of Vendure Shop API responses (GraphQL). Intentionally loose and
+// do NOT import the generated Vendure types — so that map.ts stays pure
+// (contracts only) and testable without a running Vendure.
+
+export type VId = string | number;
+
+export interface VAsset {
+  preview: string;
+  width?: number | null;
+  height?: number | null;
+}
+
+export interface VCollection {
+  id: VId;
+  slug: string;
+  name: string;
+  description?: string | null;
+  parent?: { id: VId } | null;
+}
+
+export interface VVariant {
+  id: VId;
+  sku: string;
+  name?: string | null;
+  /** Vendure stores the price as an integer in minor units (like Money). */
+  priceWithTax: number;
+  currencyCode: string;
+  stockLevel?: string | null; // 'IN_STOCK' | 'OUT_OF_STOCK' | ... (not a number in the Shop API)
+}
+
+export interface VProduct {
+  id: VId;
+  name: string;
+  slug: string;
+  description?: string | null;
+  featuredAsset?: VAsset | null;
+  assets?: VAsset[] | null;
+  variants: VVariant[];
+  collections?: VCollection[] | null;
+}
+
+export interface VOrderLine {
+  id: VId;
+  quantity: number;
+  unitPriceWithTax: number;
+  linePriceWithTax: number;
+  featuredAsset?: VAsset | null;
+  productVariant: { id: VId; sku: string; name: string; product?: { id: VId; slug?: string } | null };
+}
+
+export interface VOrder {
+  id: VId;
+  code: string;
+  state: string;
+  currencyCode: string;
+  subTotalWithTax: number;
+  totalWithTax: number;
+  createdAt?: string;
+  customer?: { emailAddress?: string | null } | null;
+  lines: VOrderLine[];
+}

package/kit/templates/backend-vendure/files/lib/seed/populate.ts

@@ -0,0 +1,22 @@
+// Vendure demo catalog (§18 equivalent): dev ONLY and when the DB is empty
+// (idempotent). Full population — Vendure populate(app, initialData,
+// productsCsv) or admin import; here — a guard + an integration point. The superadmin
+// is created by Vendure from configuration (vendure-config.ts, env).
+import type { INestApplicationContext } from '@nestjs/common';
+import { Logger, ProductService, RequestContextService } from '@vendure/core';
+
+export async function populateDemo(app: INestApplicationContext): Promise<void> {
+  if (process.env.NODE_ENV === 'production') return; // never in prod
+
+  const ctx = await app.get(RequestContextService).create({ apiType: 'admin' });
+  const { totalItems } = await app.get(ProductService).findAll(ctx, { take: 1 });
+  if (totalItems > 0) return; // idempotent: a non-empty DB — leave it alone
+
+  Logger.info(
+    '[vitrine] Vendure: empty DB in dev — populate the demo catalog via ' +
+      'populate(app, ./seed/initial-data, ./seed/products.csv) or admin import.',
+    'Vitrine',
+  );
+  // This is where Vendure populate() wires up with local initial-data + products.csv
+  // (offline, assets in static/). Left as an integration point (requires a running Vendure).
+}

package/kit/templates/backend-vendure/files/src/index.ts

@@ -0,0 +1,15 @@
+// Vendure server bootstrap (separate process: `pnpm vendure`). The Next storefront
+// (`pnpm dev`) talks to the Shop API via lib/adapter. In dev with an empty DB —
+// demo populate (guarded inside populateDemo).
+import { bootstrap } from '@vendure/core';
+import { config } from '../vendure-config.js';
+import { populateDemo } from '../lib/seed/populate.js';
+
+bootstrap(config)
+  .then(async (app) => {
+    await populateDemo(app);
+  })
+  .catch((err: unknown) => {
+    console.error('[vitrine] Vendure bootstrap failed:', err);
+    process.exit(1);
+  });

package/kit/templates/backend-vendure/files/vendure-config.ts

@@ -0,0 +1,56 @@
+// Vendure server config. DB: Postgres (DATABASE_URL) or the embedded better-sqlite3
+// in dev (zero-config, §18 equivalent). Superadmin — from env (change it for prod).
+// The Stripe plugin is wired in at tier=full with payments.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DefaultJobQueuePlugin, DefaultSearchPlugin, type VendureConfig } from '@vendure/core';
+import { AssetServerPlugin } from '@vendure/asset-server-plugin';
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+const IS_DEV = process.env.NODE_ENV !== 'production';
+
+function dbConnectionOptions(): VendureConfig['dbConnectionOptions'] {
+  const url = process.env.DATABASE_URL;
+  if (url) {
+    return { type: 'postgres', url, synchronize: IS_DEV } as VendureConfig['dbConnectionOptions'];
+  }
+  if (!IS_DEV) {
+    // In production there's no silent fallback to SQLite (§18).
+    throw new Error('[vitrine] DATABASE_URL is required in production');
+  }
+  // dev zero-config: embedded SQLite (no DB server).
+  return {
+    type: 'better-sqlite3',
+    database: path.join(dirname, '.vitrine', 'vendure.sqlite'),
+    synchronize: true,
+  } as VendureConfig['dbConnectionOptions'];
+}
+
+export const config: VendureConfig = {
+  apiOptions: {
+    port: Number(process.env.VENDURE_PORT ?? 3001),
+    adminApiPath: 'admin-api',
+    shopApiPath: 'shop-api',
+  },
+  authOptions: {
+    tokenMethod: ['bearer', 'cookie'],
+    superadminCredentials: {
+      identifier: process.env.VENDURE_SUPERADMIN_USERNAME ?? 'superadmin',
+      // dev default; for prod you must set VENDURE_SUPERADMIN_PASSWORD.
+      password: process.env.VENDURE_SUPERADMIN_PASSWORD ?? 'superadmin',
+    },
+    cookieOptions: { secret: process.env.VENDURE_COOKIE_SECRET ?? 'dev-cookie-secret' },
+  },
+  dbConnectionOptions: dbConnectionOptions(),
+  paymentOptions: {
+    paymentMethodHandlers: [
+      // + StripePlugin handler (env STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET) for tier=full with payments.
+    ],
+  },
+  plugins: [
+    DefaultJobQueuePlugin.init({}),
+    DefaultSearchPlugin.init({ bufferUpdates: false }),
+    AssetServerPlugin.init({ route: 'assets', assetUploadDir: path.join(dirname, 'static', 'assets') }),
+    // StripePlugin.init({ storeCustomersInStripe: true }),
+  ],
+};

package/kit/templates/base/files/.claude/commands/add-feature.md

@@ -0,0 +1,18 @@
+---
+description: Add a feature from the Vitrine registry and style it
+argument-hint: <feature>
+---
+
+Add the `$ARGUMENTS` feature to the project:
+
+1. `vitrine list` — check that the feature is available and not yet installed (show the list).
+2. `vitrine add $ARGUMENTS` — copies files, registers slots/blueprint, merges in
+   env and dependencies, updates `site.config.ts`, `vitrine.json`, and the table in `CLAUDE.md`.
+   The feature's dependencies are pulled in automatically.
+3. If the feature added keys to `.env.example` — suggest filling them in `.env`.
+4. `vitrine design apply` — style the new feature for the current brand (only if `/design`
+   has an export; otherwise skip).
+5. `pnpm typecheck` (or `pnpm build`) — make sure the build is green.
+6. Don't edit generated files by hand. Remind the user to commit the changes.
+
+To remove a feature — `vitrine remove <feature>` (only for `removable` ones).

package/kit/templates/base/files/.claude/commands/design.md

@@ -0,0 +1,14 @@
+---
+description: Apply the design from /design to the tokens (vitrine design apply)
+---
+
+Apply the client design:
+
+1. Check that the `/design` folder has a brand export (something besides `README.md`: tokens,
+   screenshots, assets). If it's empty — ask the user to add the export and stop.
+2. `vitrine design apply` — a wrapper over Claude Code: it sets ONLY the CSS variable values
+   in `theme/client.css`, without touching logic/data/routing/structure. The token set is closed.
+3. Show the `theme/client.css` diff and briefly describe the palette/typography/spacing changes.
+4. The step is idempotent — re-running converges. Run it again if needed.
+
+If Claude Code isn't found in PATH — point to it via `--bin` or `VITRINE_CLAUDE_BIN`.

package/kit/templates/base/files/.claude/commands/doctor.md

@@ -0,0 +1,15 @@
+---
+description: Check project consistency and fix discrepancies
+---
+
+Check the project's health:
+
+1. `vitrine doctor` — reconciles `vitrine.json` ↔ files ↔ packages (`package.json`) ↔ env (`.env.example`).
+2. Work through the output. Each issue has a suggested fix:
+   - missing file/slot/provider/dependency → `vitrine add <feature>` (reinstalls and regenerates);
+   - version in the repo ≠ registry → `vitrine update <feature>`;
+   - feature not found in the registry → `vitrine kit update`;
+   - missing env key → add it to `.env.example`/`.env`;
+   - no design-instruction block in `CLAUDE.md` → refresh it (`kit update` brings it).
+3. Apply the fixes (prefer CLI commands over hand edits), then re-run `vitrine doctor`
+   until it's green. Report anything left that needs a user decision (e.g. secrets).