CLI Commands

Command-line interface for development, building, and deployment workflows. The CLI provides three main commands for different stages of the component development lifecycle.

Capabilities

Serve Command

Starts the development server with hot module reloading for interactive component development.

ladle serve [options]
# Alias: ladle dev [options]

Options:

• --host <host> - Specify host address (default: localhost)
• --port <port> - Specify port number (default: 61000)
• --stories <pattern> - Glob pattern for story files (default: "src/**/*.stories.{js,jsx,ts,tsx,mdx}")
• --theme <theme> - Default theme ("light" | "dark" | "auto")
• --config <path> - Path to config file (default: ".ladle/config.mjs")
• --viteConfig <path> - Path to Vite config file
• --base <path> - Base path for URLs
• --mode <mode> - Environment mode
• --noWatch - Disable file watching

Usage Examples:

# Start development server on default port
ladle serve

# Start with custom port and host
ladle serve --port 3000 --host 0.0.0.0

# Use custom story pattern
ladle serve --stories "components/**/*.story.tsx"

# Start in dark theme mode
ladle serve --theme dark

Build Command

Builds a static production version of the component library for deployment.

ladle build [options]

Options:

• --outDir <directory> - Output directory for build files (default: "build")
• --stories <pattern> - Glob pattern for story files
• --theme <theme> - Default theme for production build
• --config <path> - Path to config file
• --viteConfig <path> - Path to Vite config file
• --base <path> - Base path for URLs in production
• --mode <mode> - Build mode (default: "production")

Usage Examples:

# Build to default directory
ladle build

# Build to custom directory
ladle build --outDir dist

# Build with custom base path for CDN deployment
ladle build --base /my-components/

# Build with specific theme
ladle build --theme light

Return Behavior: The build command returns a boolean indicating success (true) or failure (false) when used programmatically.

Preview Command

Starts a preview server to test the built static files locally before deployment.

ladle preview [options]

Options:

• --outDir <directory> - Directory containing built files (default: "build")
• --host <host> - Preview server host
• --port <port> - Preview server port (default: 8080)
• --config <path> - Path to config file
• --viteConfig <path> - Path to Vite config file
• --base <path> - Base path for URLs
• --mode <mode> - Preview mode

Usage Examples:

# Preview built files on default port
ladle preview

# Preview on custom port
ladle preview --port 9000

# Preview files from custom build directory
ladle preview --outDir dist

Command Line Integration

Global Installation

# Install globally for system-wide access
npm install -g @ladle/react

# Use from anywhere
ladle serve

Local Installation

# Install as dev dependency
npm install --save-dev @ladle/react

# Use via npm scripts
npm run ladle serve

# Or via npx
npx ladle serve

Package Scripts Integration

Add Ladle commands to your package.json:

{
  "scripts": {
    "dev": "ladle serve",
    "build-components": "ladle build",
    "preview-components": "ladle preview",
    "dev:components": "ladle serve --port 3001"
  }
}

Configuration Integration

All CLI commands respect configuration from .ladle/config.mjs:

// .ladle/config.mjs
export default {
  stories: "src/**/*.stories.{js,jsx,ts,tsx}",
  port: 3000,
  outDir: "component-docs",
  theme: "dark"
};

CLI options override configuration file settings when provided.