npm package: @hydrogen-ui/cli
Description: CLI tools for Hydrogen UI development
Latest version: 0.0.1

# @hydrogen-ui/cli

A powerful command-line interface for scaffolding and managing Hydrogen UI components, themes, and design tokens in your Shopify Hydrogen storefront.

## Installation

```bash
npm install -g @hydrogen-ui/cli
# or
yarn global add @hydrogen-ui/cli
# or
pnpm add -g @hydrogen-ui/cli
# or
bun add -g @hydrogen-ui/cli
```

## Quick Start

```bash
# Initialize Hydrogen UI in your project
hydrogen-ui init

# Add a component to your project
hydrogen-ui add button

# Create a new custom component
hydrogen-ui create component MyCustomButton

# List available themes
hydrogen-ui theme list
```

## Commands

### `hydrogen-ui init`

Initializes Hydrogen UI in your existing project. This command will:

- Detect your package manager automatically
- Install necessary Hydrogen UI packages
- Create configuration files
- Set up theme and token integration
- Import CSS variables into your main CSS file

#### Options

- `--yes, -y` - Skip prompts and use default configuration
- `--typescript` - Use TypeScript (also prompted interactively)
- `--theme <theme>` - Pre-select a theme (dawn, craft, studio, b2b, thnk)

#### Example

```bash
# Interactive initialization
hydrogen-ui init

# Non-interactive with defaults
hydrogen-ui init --yes

# Initialize with specific theme
hydrogen-ui init --theme studio --typescript
```

### `hydrogen-ui add [component]`

Adds a pre-built component to your project with customizable wrapper. This creates a local component that extends the base Hydrogen UI component, allowing you to add custom props and behavior.

#### Available Components

**Layout Components:**
- `box` - Flexible container component
- `flex` - Flexbox layout component
- `stack` - Vertical stack layout with consistent spacing
- `grid` - CSS Grid layout component

**Typography Components:**
- `text` - Styled text component
- `heading` - Heading component with size variants
- `link` - Styled link component with router integration
- `code` - Code snippet display component

**Form Components:**
- `button` - Styled button with variants
- `input` - Text input with validation support
- `select` - Dropdown select component
- `checkbox` - Checkbox input component
- `radio` - Radio button component
- `optim-input` - Optimistically updated input

**Shopify Components:**
- `money` - Currency display component
- `product-card` - Product display card
- `cart-line-item` - Cart item display
- `add-to-cart-button` - Product add to cart button
- `product-price` - Product price display
- `product-image` - Optimized product image
- `variant-selector` - Product variant picker
- `cart-summary` - Cart totals display
- `pagination` - Collection pagination
- `collection-grid` - Product collection grid
- `filter-drawer` - Collection filter UI

**Media Components:**
- `image` - Optimized image component
- `external-video` - External video embed
- `media-file` - Generic media display
- `model-viewer` - 3D model viewer

#### Example

```bash
# Add with interactive selection
hydrogen-ui add

# Add specific component
hydrogen-ui add button

# Add multiple components
hydrogen-ui add button input select
```

#### Generated Files

When you add a component, the CLI creates:

```
src/components/Button/
├── Button.tsx          # Your customizable wrapper
├── Button.types.ts     # TypeScript interface extending base props
├── index.ts           # Clean export
└── README.md          # Documentation (if component has dependencies)
```

Example generated wrapper:

```tsx
// Button.tsx
import React from 'react';
import { Button as HydrogenButton } from '@hydrogen-ui/components';
import type { ButtonProps } from './Button.types';

export const Button: React.FC<ButtonProps> = ({ 
  children,
  customProp,
  ...props 
}) => {
  // Add your custom logic here
  
  return (
    <HydrogenButton {...props}>
      {children}
    </HydrogenButton>
  );
};
```

### `hydrogen-ui create <type> [name]`

Creates new components, themes, or tokens from scratch.

#### Component Creation

```bash
# Create a new component interactively
hydrogen-ui create component

# Create with name
hydrogen-ui create component MyCustomCard

# With options
hydrogen-ui create component MyCustomCard --typescript --stories --tests
```

**Options:**
- `--typescript` - Use TypeScript (default: true)
- `--stories` - Include Storybook stories
- `--tests` - Include test file with Vitest setup

**Generated Structure:**
```
src/components/MyCustomCard/
├── MyCustomCard.tsx
├── MyCustomCard.types.ts
├── index.ts
├── __tests__/
│   └── MyCustomCard.test.tsx
└── MyCustomCard.stories.tsx
```

#### Theme Creation

```bash
# Create a custom theme
hydrogen-ui create theme my-brand

# Extend existing theme
hydrogen-ui create theme my-brand --extends dawn
```

### `hydrogen-ui theme`

Manage and preview themes in your project.

#### Subcommands

**`theme list`** - Display all available themes

```bash
hydrogen-ui theme list

# Output:
# Available themes:
#   
# dawn (default)
#   Clean and minimal design with excellent readability
#   Primary: #000000
#   
# craft
#   Artisanal feel with warm colors and organic shapes  
#   Primary: #8B4513
#   
# studio
#   Modern and bold with high contrast
#   Primary: #FF006E
#   
# b2b
#   Professional theme for business applications
#   Primary: #0066CC
#   
# thnk
#   Creative and playful with vibrant colors
#   Primary: #7C3AED
```

**`theme preview <theme>`** - Preview a theme in the browser (coming soon)

**`theme export <theme>`** - Export theme tokens (coming soon)

```bash
# Export as JSON
hydrogen-ui theme export dawn --format json

# Export as CSS variables
hydrogen-ui theme export dawn --format css

# Export as JavaScript
hydrogen-ui theme export dawn --format js
```

### `hydrogen-ui token`

Manage design tokens throughout your project.

#### Subcommands

**`token list`** - Show available token categories

```bash
hydrogen-ui token list

# Output:
# Available token categories:
# - color (primary, secondary, text, background, etc.)
# - spacing (xs, sm, md, lg, xl, 2xl, etc.)
# - typography (fontSize, fontWeight, lineHeight, etc.)
# - radius (sm, md, lg, full)
# - shadow (sm, md, lg, xl)
# - animation (duration, easing)
# - breakpoint (sm, md, lg, xl, 2xl)
# - semantic (success, warning, error, info)
```

**`token get <category>`** - Display token values (coming soon)

**`token override <token> <value>`** - Override token values (coming soon)

## Configuration

### hydrogen-ui.config.js

The CLI creates this configuration file in your project root:

```javascript
// hydrogen-ui.config.js
module.exports = {
  // Selected theme
  theme: 'dawn',
  
  // Component directory
  componentDir: 'src/components',
  
  // TypeScript usage
  typescript: true,
  
  // Installed packages
  packages: [
    '@hydrogen-ui/core',
    '@hydrogen-ui/components',
    '@hydrogen-ui/themes',
    '@hydrogen-ui/tokens'
  ],
  
  // Custom token overrides
  tokens: {
    color: {
      primary: '#custom-color'
    }
  }
};
```

### Provider Setup

The CLI automatically sets up the Hydrogen UI provider in your app:

```tsx
// app/root.tsx or similar
import { HydrogenUIProvider } from '@hydrogen-ui/core';
import { dawm } from '@hydrogen-ui/themes';

export default function App() {
  return (
    <HydrogenUIProvider theme={dawn}>
      {/* Your app */}
    </HydrogenUIProvider>
  );
}
```

## Package Manager Detection

The CLI automatically detects your package manager by checking for:

1. Lock files (`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`)
2. Available commands in your system
3. Falls back to npm if none detected

## Component Dependencies

Some components depend on others. The CLI handles this automatically and documents dependencies:

```bash
# When adding ProductCard, these dependencies are documented:
# - Box (container)
# - Text (product title) 
# - Money (price display)
# - Button (add to cart)
```

## Development Workflow

1. **Initialize** your project with Hydrogen UI
   ```bash
   hydrogen-ui init --theme studio
   ```

2. **Add** pre-built components you need
   ```bash
   hydrogen-ui add product-card collection-grid filter-drawer
   ```

3. **Create** custom components for unique needs
   ```bash
   hydrogen-ui create component FeaturedProduct --stories --tests
   ```

4. **Customize** themes and tokens
   ```bash
   hydrogen-ui theme list
   hydrogen-ui token override color.primary "#FF6B6B"
   ```

5. **Build** your storefront with consistent design system

## Best Practices

### Component Organization

Keep your components organized with the generated structure:

```
src/components/
├── atoms/           # Basic building blocks
│   ├── Button/
│   ├── Input/
│   └── Text/
├── molecules/       # Composed components
│   ├── ProductCard/
│   └── CartLineItem/
└── organisms/       # Complex components
    ├── CollectionGrid/
    └── FilterDrawer/
```

### Extending Components

Always extend base components rather than modifying them directly:

```tsx
// ✅ Good - Extend base component
import { Button as BaseButton } from '@hydrogen-ui/components';

export const Button = ({ variant, ...props }) => {
  const customClass = variant === 'cta' ? 'cta-button' : '';
  return <BaseButton className={customClass} {...props} />;
};

// ❌ Bad - Copy and modify
// Don't copy the entire component code
```

### Theme Customization

Create theme variants for different contexts:

```javascript
// hydrogen-ui.config.js
const themes = {
  default: 'dawn',
  seasonal: {
    summer: 'craft',
    holiday: 'thnk'
  }
};
```

## Troubleshooting

### Common Issues

**Components not found after adding**
- Ensure you've restarted your dev server
- Check that imports match the component directory structure
- Verify `hydrogen-ui.config.js` has correct `componentDir`

**TypeScript errors**
- Run `npm run typecheck` to identify issues
- Ensure `@types/react` is installed
- Check that component `.types.ts` files are properly generated

**Theme not applying**
- Verify `HydrogenUIProvider` wraps your app
- Check that theme is imported from `@hydrogen-ui/themes`
- Clear browser cache and restart dev server

### Debug Mode

Run commands with debug output:

```bash
DEBUG=hydrogen-ui:* hydrogen-ui add button
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.

## License

MIT © Hydrogen UI Team