@shopkit/cli

CLI tools for Shopkit storefront development. Provides generators for themes, widgets, and templates, plus validators for structure compliance.

Installation

# In your monorepo
bun add @shopkit/cli

Usage

Generate Commands (Angular-style)

# Generate a new theme
bun run g theme <name> [--lang=en]
bun run g theme dawn
bun run g t "My Store" --lang=hi

# Generate a new widget
bun run g widget <name> [--scope=common]
bun run g widget HeroBanner
bun run g w ProductCard --scope=common

# Generate a new template
bun run g template <name> [--theme=<theme>]
bun run g template cart
bun run g tp checkout --theme=dawn

Validators

# Validate widget structures
bun run validate:widget
bun run validate:widget --staged-only

# Validate template structures
bun run validate:template
bun run validate:template --theme=dawn

Interactive Mode

bun run cli

Theme Generator Output

Running bun run g theme <name> creates the following structure:

src/themes/{theme-id}/
├── theme.json                    # Theme configuration
├── templates/
│   ├── home/default.ts           # Home page template
│   ├── home-b/default.ts         # Home A/B variant
│   ├── products/default.ts       # Products page template
│   ├── products-b/default.ts     # Products A/B variant
│   ├── collection/default.ts     # Collection page template
│   ├── collection-b/default.ts   # Collection A/B variant
│   ├── orders/default.ts         # Orders/Thank You page
│   └── variant-registry.ts       # Template registry
└── locales/
    ├── common/{lang}.json        # Common translations (logo, site_name, etc.)
    └── pages/
        ├── home/{lang}.json
        ├── home-b/{lang}.json
        ├── products/{lang}.json
        ├── products-b/{lang}.json
        ├── collections/{lang}.json
        ├── collections-b/{lang}.json
        └── orders/{lang}.json

Template Structure

All generated templates follow this consistent pattern:

// Each template has three sections:
{
  sections: [
    // 1. Header Section
    {
      type: SECTION_TYPES.HEADER_SECTION,
      widgets: [{ type: WIDGET_TYPES.Header }]
    },
    // 2. Main Content Section
    {
      type: SECTION_TYPES.CONTENT_SECTION,
      widgets: [{
        type: WIDGET_TYPES.PageContent,
        settings: {
          heading: "t:{page_name}.heading",
          description: "t:{page_name}.description"
        }
      }]
    },
    // 3. Footer Section
    {
      type: SECTION_TYPES.FOOTER_SECTION,
      widgets: [{ type: WIDGET_TYPES.Footer }]
    }
  ]
}

Translation Key Structure

Each page has a corresponding locale file with this structure:

{
  "{page_name}": {
    "page_title": "Page Title",
    "heading": "Page Heading",
    "description": "Welcome to the page."
  }
}

Translation keys are referenced in templates using the t: prefix:

• t:home.heading - Resolves to the heading from home locale
• t:products.description - Resolves to the description from products locale

Essential Widgets

The theme generator creates these essential widgets if they don't exist:

| Widget | Purpose | |--------|---------| | Header | Site header with navigation | | Footer | Site footer with links | | PageContent | Displays translated heading and description |

A/B Variant Templates

Templates with -b suffix (home-b, products-b, collection-b) are for A/B testing:

• Use the same translation structure as their base templates
• Allow different layouts/widgets for experimentation
• Can be served to different user segments

Widget Generator Output

Running bun run g widget <name> creates:

src/widgets/{scope}/{WidgetName}/
├── index.tsx           # Widget entry point with variant resolution
├── types.ts            # TypeScript interfaces (Settings, Data, Props)
├── variants.ts         # Variant registry
└── V1/
    └── index.tsx       # Default V1 variant component

Template Generator Output

Running bun run g template <name> creates:

src/themes/{theme}/templates/{template-name}/
└── default.ts          # Template configuration

src/themes/{theme}/locales/pages/{template-name}/
└── {lang}.json         # Translation file for each supported language

Programmatic Usage

import {
  generateWidget,
  generateTheme,
  generateTemplate,
  validateWidgets,
  validateTemplates,
} from "@shopkit/cli";

// Generate a widget programmatically
await generateWidget({ name: "HeroBanner", scope: "common" });

// Generate a theme
await generateTheme({ name: "dawn", lang: "en" });

// Validate widgets
const { passed, errors } = await runWidgetValidation();

Options

| Option | Description | Default | |--------|-------------|---------| | --lang=<code> | Default language for theme | en | | --scope=<name> | Widget scope/namespace | common | | --theme=<name> | Theme name for template | - | | --staged-only | Validate only staged files | false | | --skip-generate | Skip registry generation | false |

License

MIT