@vitrine-kit/vitrine 0.3.1 → 0.4.1

package/kit/templates/backend-payload/files/lib/seed/richtext.ts

@@ -0,0 +1,26 @@
+// Minimal Lexical richText value from plain text — for the description of
+// demo products during seeding.
+export function plainToRichText(text: string): unknown {
+  return {
+    root: {
+      type: 'root',
+      format: '',
+      indent: 0,
+      version: 1,
+      direction: 'ltr',
+      children: [
+        {
+          type: 'paragraph',
+          format: '',
+          indent: 0,
+          version: 1,
+          direction: 'ltr',
+          textFormat: 0,
+          children: [
+            { type: 'text', text, format: 0, style: '', mode: 'normal', detail: 0, version: 1 },
+          ],
+        },
+      ],
+    },
+  };
+}

package/kit/templates/backend-payload/files/lib/seed/run.ts

@@ -0,0 +1,51 @@
+// Demo seed (§18.2): runs from Payload's onInit. Idempotent (guarded by
+// shouldRunDevTask: dev only + empty collection). Images are local
+// placeholders from seed-assets/ (no network).
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Payload } from 'payload';
+import { demoCategories, demoProducts } from './demo.js';
+import { shouldRunDevTask } from './guards.js';
+import { plainToRichText } from './richtext.js';
+
+const seedAssets = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../seed-assets');
+
+export async function seedDemo(payload: Payload): Promise<void> {
+  const isProd = process.env.NODE_ENV === 'production';
+  const { totalDocs } = await payload.count({ collection: 'products' });
+  if (!shouldRunDevTask({ isProd, existingCount: totalDocs })) return;
+
+  const categoryId = new Map<string, string | number>();
+  for (const c of demoCategories) {
+    const doc = await payload.create({ collection: 'categories', data: { slug: c.slug, title: c.title } });
+    categoryId.set(c.slug, doc.id);
+  }
+
+  for (const p of demoProducts) {
+    const media = await payload.create({
+      collection: 'media',
+      data: { alt: p.title },
+      filePath: path.join(seedAssets, p.image),
+    });
+    const catId = categoryId.get(p.category);
+    const product = await payload.create({
+      collection: 'products',
+      data: {
+        slug: p.slug,
+        title: p.title,
+        description: plainToRichText(p.description),
+        categories: catId ? [catId] : [],
+        images: [media.id],
+        seo: { title: p.seo.title, description: p.seo.description, image: media.id },
+      },
+    });
+    for (const v of p.variants) {
+      await payload.create({
+        collection: 'variants',
+        data: { sku: v.sku, price: v.price, stock: v.stock, product: product.id },
+      });
+    }
+  }
+
+  payload.logger.info('[vitrine] demo seed: created 5 products');
+}

package/kit/templates/backend-payload/files/next.config.mjs

@@ -0,0 +1,10 @@
+// backend-payload: wrap the Next config in withPayload (mounts the Payload admin and
+// API into Next). output: 'standalone' — for the Docker image (VPS).
+import { withPayload } from '@payloadcms/next/withPayload';
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  output: 'standalone',
+};
+
+export default withPayload(nextConfig);

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);
+  });