@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

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

# 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

# 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

# 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:

// 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

# 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

# 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

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)

# 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

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:

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

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

# 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

   hydrogen-ui init --theme studio

2. Add pre-built components you need

   hydrogen-ui add product-card collection-grid filter-drawer

3. Create custom components for unique needs

   hydrogen-ui create component FeaturedProduct --stories --tests

4. Customize themes and tokens

   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:

// ✅ 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:

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

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

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT © Hydrogen UI Team