npm package: @shopkit/cli
Description: CLI tools for Shopkit storefront development
Latest version: 0.2.0

# @shopkit/cli

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

## Installation

```bash
# In your monorepo
bun add @shopkit/cli
```

## Usage

### Generate Commands (Angular-style)

```bash
# 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

```bash
# 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

```bash
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:

```typescript
// 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:

```json
{
  "{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

```typescript
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