@dutchiesdk/ecommerce-sdk-cli

CLI and developer test bench for building and previewing Dutchie E-Commerce Pro themes.

Quick Start

Install as a dev dependency in your themes project:

pnpm add -D @dutchiesdk/ecommerce-sdk-cli

Scaffold a new theme:

npx @dutchiesdk/ecommerce-sdk-cli generate

Then start the dev server:

npx @dutchiesdk/ecommerce-sdk-cli dev

This starts the test bench at https://localhost:4000 with hot reload. Themes are discovered automatically from ./src/themes/ relative to your working directory.

Dev server TLS certificate

The dev server is HTTPS so that Module Federation chunks can be loaded into the real https://*.dutchie.com storefront for live preview (browsers block HTTP subresources on HTTPS pages).

The cert is generated and cached at <your-project>/.dutchie-sdk/dev-certs/ and reused across restarts — so any "Always Trust" decision in your OS keychain only has to be made once per project. Add .dutchie-sdk/ to your .gitignore.

For zero browser warnings (recommended): install mkcert once. The dev server will detect it and issue certs signed by your locally-installed CA — no warnings, no manual trust step.

brew install mkcert nss   # nss is only needed for Firefox
mkcert -install           # one-time: installs the local CA into your system trust store

After that, every dev run uses mkcert automatically. If mkcert isn't installed, the dev server falls back to a cached self-signed cert and prints a one-line hint pointing here.

CLI

npx @dutchiesdk/ecommerce-sdk-cli <command> [options]

Commands

| Command | Description | |---------|-------------| | dev | Start the test bench dev server with hot reload (HTTPS) | | build | Production build — outputs Module Federation bundles to ./dist/ | | generate | Scaffold a new theme with interactive preset and component selection | | skill | Copy the AI theme-styling skill doc into your project | | mcp | Search/fetch SDK docs (subcommands), or run as stdio proxy for MCP clients |

Options

| Flag | Default | Description | |------|---------|-------------| | --themes-dir <path> | ./src/themes | Path to the directory containing theme folders (dev, build, generate) | | --latency <ms> | 0 | Simulated latency in ms for dev server requests (dev) | | --name <name> | — | Theme name in kebab-case, skips the name prompt (generate) | | --out <path> | ./THEME_STYLING_SKILL.md | Output path for the skill doc (skill) |

Environment Variables

| Variable | Description | |----------|-------------| | PRODUCTION_ASSET_URL | Asset prefix for production builds (CDN URL) | | CF_PAGES_URL | Cloudflare Pages URL (fallback for asset prefix) |

Custom Plugins

You can extend the underlying Rsbuild configuration by adding a dutchie-sdk.config.ts file to your project root. The CLI picks it up automatically on dev and build — no flags required.

// dutchie-sdk.config.ts
import { defineConfig } from '@dutchiesdk/ecommerce-sdk-cli/config';
import { pluginImageCompress } from '@rsbuild/plugin-image-compress';

export default defineConfig({
  plugins: [pluginImageCompress()],
});

defineConfig is an identity function that provides TypeScript autocompletion for the config object.

The CLI resolves config files in this order (first match wins):

1. dutchie-sdk.config.ts
2. dutchie-sdk.config.js
3. dutchie-sdk.config.mjs

User plugins are appended after the CLI's built-in plugins (React, styled-components, Module Federation), so they can hook into or post-process the build without interfering with core behavior.

Theme Generator

The generate command walks you through creating a new theme interactively:

1. Name — kebab-case theme name (or pass --name to skip the prompt)
2. Preset — color/style starting point (default, dark-modern, earthy-green, forest-moss, midnight-luxe, neon-electric, ocean-blue, rose-garden, slate-minimal, sunset-glow, terracotta, warm-amber)
3. Components — pick which extension slots to scaffold (header, navigation, footer, hero, product cards, interstitials, pages, etc.)

The generator writes a ready-to-run theme folder under your --themes-dir with a wired-up index.tsx and per-slot component files. After generating, run ecommerce-sdk-cli dev to preview it immediately.

To get the companion AI skill doc for theme styling:

npx @dutchiesdk/ecommerce-sdk-cli skill

This copies THEME_STYLING_SKILL.md into your project root (or the path given by --out), which you can point AI coding assistants at for guided theme customization.

Test Bench

The dev server includes a full-featured theme test bench with:

• Sidebar — Searchable list of all discovered themes with slot indicator badges
• Storefront Preview — Renders Header, Hero, Footer, and custom pages with mock data
• Product Card Preview — Grid and list card rendering with mock product data
• Slot Inspector — Visual audit of which RemoteModuleRegistry slots a theme implements, with per-slot context badges (Storefront / Kiosk)
• Menu Context Toggle — Switch between Storefront and Kiosk contexts to preview MenuSpecificRemoteComponent variants
• Live Preview — Open your theme on a real Dutchie dispensary storefront by entering a store cname; loads your local Module Federation manifest against the production site
• Viewport Controls — Desktop (1440px), Tablet (768px), and Mobile (375px) presets
• Action Log — Captures mock action calls (addToCart, goToCheckout, etc.) with timestamps
• URL State — Theme, view mode, viewport, and menu context are synced to query params for bookmarkable states

Test Fixtures

The package exports mock data factories for use in theme unit tests:

import {
  mockedBoundaryData,
  mockedTheme,
  mockedProductCardGridItems,
  mockedProductCardListItems,
  getRandomLocation,
} from '@dutchiesdk/ecommerce-sdk-cli/support';

| Export | Returns | |--------|---------| | mockedBoundaryData(log?) | CommerceComponentsDataInterface with mock location, user, cart, data loaders, and actions | | mockedTheme() | Theme object with MUI breakpoints | | mockedProductCardGridItems(log?) | Array of ProductCardGridProps (4 mock products) | | mockedProductCardListItems(log?) | Array of ProductCardListItemProps (4 mock products) | | getRandomLocation() | Random Dispensary object via faker |

The optional log parameter accepts a callback for capturing action calls in the test bench UI.

Theme Project Setup

A minimal themes project needs:

my-themes/
  package.json
  dutchie-sdk.config.ts  # optional — custom Rsbuild plugins
  src/
    themes/
      my-theme/
        index.tsx      # default export satisfies RemoteModuleRegistry
        store-front/
          header.tsx
          footer.tsx

With this package.json:

{
  "scripts": {
    "dev": "ecommerce-sdk-cli dev",
    "build": "ecommerce-sdk-cli build",
    "generate": "ecommerce-sdk-cli generate"
  },
  "dependencies": {
    "@dutchiesdk/ecommerce-extensions-sdk": ">=0.21.0",
    "react": "^18.0",
    "react-dom": "^18.0",
    "styled-components": "^5.3.0"
  },
  "devDependencies": {
    "@dutchiesdk/ecommerce-sdk-cli": ">=0.24.0"
  }
}

MCP / Documentation

The mcp command gives both humans and AI coding assistants access to the Dutchie SDK documentation. It can run in two modes:

1. One-shot subcommands (most useful in shells, scripts, and CLI-based AI agents) — query the docs directly without configuring an MCP client.
2. Stdio proxy (default when no subcommand is given) — bridges stdio to the remote GitBook-hosted MCP server for clients like Cursor, VS Code, and Claude Desktop.

One-shot subcommands

# Search the docs for a question or topic
npx @dutchiesdk/ecommerce-sdk-cli mcp search "how do I customize the product card"

# Cap the number of results and emit JSON for piping
npx @dutchiesdk/ecommerce-sdk-cli mcp search "data bridge" --limit 3 --json

# Fetch the full markdown of a specific docs page (URL surfaced by `mcp search`)
npx @dutchiesdk/ecommerce-sdk-cli mcp page "https://docs.dutchie.com/dutchie-core-docs/dutchie-ecommerce-pro-sdk/core-concepts/data-bridge"

# List the tools exposed by the docs MCP server
npx @dutchiesdk/ecommerce-sdk-cli mcp tools

Flags: --json emits raw structured output; --limit N caps mcp search results.

Stdio proxy

For MCP-aware editors and assistants, run with no subcommand (or mcp proxy explicitly) and configure your client to spawn it:

npx @dutchiesdk/ecommerce-sdk-cli mcp

Cursor / VS Code

Add to .cursor/mcp.json (or .vscode/mcp.json):

{
  "mcpServers": {
    "dutchie-sdk-docs": {
      "command": "npx",
      "args": ["@dutchiesdk/ecommerce-sdk-cli", "mcp"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "dutchie-sdk-docs": {
      "command": "npx",
      "args": ["@dutchiesdk/ecommerce-sdk-cli", "mcp"]
    }
  }
}

Build Output

The build command produces Module Federation bundles compatible with the Dutchie Ecommerce Pro:

dist/
  customer_themes.js       # Module Federation entry
  mf-manifest.json         # Manifest for remote loading
  static/
    js/async/              # Theme chunk bundles
    image/                 # Optimized theme assets

Peer Dependencies

• react ^18.0
• react-dom ^18.0
• @dutchiesdk/ecommerce-extensions-sdk >=0.21.0