@duongthiu/onex-cli

CLI tool for OneX theme development - scaffold themes, sections, blocks, and components with ease.

Uses @duongthiu/onex-core for the core theme system.

Installation

# Install in your OneX project
npm install -D @duongthiu/onex-cli

# Or use globally
npm install -g @duongthiu/onex-cli

# Or use via npx
npx @duongthiu/onex-cli <command>

Commands

onex init [theme-name]

Initialize a new OneX theme with complete structure.

Options:

• -t, --template <template> - Template to use (default, minimal)

Example:

onex init my-theme
onex init my-store -t ecommerce

Generated structure:

src/themes/my-theme/
├── manifest.ts           # Theme metadata and exports
├── theme.config.ts       # Design tokens (colors, typography, spacing)
├── theme.layout.ts       # Header/footer configuration
├── index.ts              # Main exports
├── sections/             # Theme-specific sections
├── blocks/               # Theme-specific blocks
└── pages/
    └── home.ts           # Default home page config

onex create:section <name> (alias: cs)

Create a new section with schema and template files.

Options:

• -t, --theme <theme> - Theme to create section in
• -c, --category <category> - Section category (headers, content, footers, etc.)
• --template <template> - Initial template variant

Example:

onex create:section hero -t my-theme -c heroes
onex cs featured-products -t my-store -c ecommerce

Generated files:

src/themes/my-theme/sections/hero/
├── hero.schema.ts        # Section schema with settings
├── hero-default.tsx      # Default template component
└── index.ts              # Exports

onex create:block <name> (alias: cb)

Create a new block component (shared or theme-specific).

Options:

• -t, --theme <theme> - Theme to create block in (optional, defaults to shared)

Example:

onex create:block product-card
onex cb testimonial-item -t my-theme

Generated files:

src/features/blocks/product-card/
├── product-card.schema.ts    # Block schema with settings
├── product-card.tsx          # Block component
└── index.ts                  # Exports

onex create:component <name> (alias: cc)

Create a new UI component.

Options:

• -t, --type <type> - Component type (ui, form, layout, content)

Example:

onex create:component icon-badge
onex cc custom-input -t form

Generated files:

src/features/components/icon-badge/
├── icon-badge.schema.ts      # Component schema with content/style fields
├── icon-badge.tsx            # Component implementation
└── index.ts                  # Exports

onex list

Display project inventory (themes, sections, blocks, components).

Options:

• -s, --sections - List sections only
• -b, --blocks - List blocks only
• -c, --components - List components only
• -t, --theme <theme> - Filter by theme

Example:

onex list
onex list -s -t my-theme
onex list --blocks

Features

Interactive Prompts

All commands feature interactive prompts for missing options:

• Theme selection from available themes
• Category selection with validation
• Display names and descriptions
• Template preferences

Validation

• Name Validation: Ensures kebab-case format (e.g., my-section, product-card)
• Theme Validation: Checks theme existence before creating sections/blocks
• Category Validation: Validates against predefined categories
• Project Detection: Ensures commands run within a OneX project

Smart Templates

Generated files include:

• Proper TypeScript types from @onex/core
• Best practice component structure
• Commented TODOs for customization
• Responsive design patterns
• Accessibility considerations

Beautiful Output

• Color-coded messages (success, error, warning, info)
• Loading spinners for file operations
• Clear next steps after each command
• Relative file paths for easy navigation

Usage in Project

Option 1: Via pnpm scripts

Add to package.json:

{
  "scripts": {
    "onex": "node packages/cli/bin/onex.js"
  }
}

Then use:

pnpm onex list
pnpm onex create:section hero -t my-theme

Option 2: Direct execution

node packages/cli/bin/onex.js list
node packages/cli/bin/onex.js create:section hero

Option 3: Global installation

npm install -g @duongthiu/onex-cli
onex list
onex create:section hero

Development

Building the CLI

cd packages/cli
pnpm build

Testing locally

# From project root
node packages/cli/bin/onex.js --help
node packages/cli/bin/onex.js list

Type Checking

pnpm type-check

Linting

pnpm lint

Architecture

File Structure

packages/cli/
├── src/
│   ├── cli.ts                  # Main CLI entry point
│   ├── index.ts                # Programmatic API
│   ├── commands/
│   │   ├── init.ts             # Theme initialization
│   │   ├── create-section.ts   # Section scaffolding
│   │   ├── create-block.ts     # Block scaffolding
│   │   ├── create-component.ts # Component scaffolding
│   │   └── list.ts             # Project inventory
│   └── utils/
│       ├── logger.ts           # Console output utilities
│       ├── file-helpers.ts     # File operations
│       └── validators.ts       # Input validation
├── bin/
│   └── onex.js                 # Executable entry point
└── package.json

Dependencies

• commander: CLI framework and command parsing
• inquirer: Interactive prompts
• chalk: Terminal string styling
• ora: Elegant terminal spinners
• fs-extra: Enhanced file system operations
• ejs: Template rendering (for future template system)
• glob: File pattern matching

Next Steps

After generating files:

1. Sections:

   • Customize section.schema.ts with your settings
   • Implement template component in section-default.tsx
   • Register in theme manifest.ts

2. Blocks:

   • Define settings in block.schema.ts
   • Implement component in block.tsx
   • Register in src/lib/registry/block-registry.ts

3. Components:

   • Customize content/style fields in component.schema.ts
   • Implement component in component.tsx
   • Register in src/lib/registry/component-registry.ts

Examples

Creating a complete feature section

# 1. Create theme
onex init ecommerce-theme

# 2. Create hero section
onex create:section hero -t ecommerce-theme -c heroes

# 3. Create product blocks
onex create:block product-card
onex create:block product-grid

# 4. Create components
onex create:component price-tag -t ui
onex create:component add-to-cart -t ui

# 5. Check inventory
onex list -t ecommerce-theme

Quick section creation

# Create with all options
onex cs testimonials -t my-theme -c testimonials

# Interactive mode (prompts for options)
onex cs testimonials

License

MIT