CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-react-styleguidist

React components style guide generator with live development server and interactive documentation

—

Pending
Overview
Eval results
Files

cli-commands.mddocs/

CLI Commands

Command-line interface for React Styleguidist providing essential operations for building and serving styleguides. The CLI is ideal for integration with npm scripts, build processes, and CI/CD pipelines.

Capabilities

Build Command

Build a static styleguide for production deployment.

styleguidist build [options]

Options:
  --config <path>    Path to configuration file
  --verbose          Print detailed build information

Usage Examples:

# Build with default config (looks for styleguide.config.js)
styleguidist build

# Build with custom config file
styleguidist build --config ./custom-styleguide.config.js

# Build with verbose output for debugging
styleguidist build --verbose

# Build from npm script
npm run styleguide:build

Example npm scripts:

{
  "scripts": {
    "styleguide:build": "styleguidist build",
    "styleguide:build:prod": "NODE_ENV=production styleguidist build --verbose",
    "styleguide:build:custom": "styleguidist build --config configs/styleguide.config.js"
  }
}

Server Command

Start a development server with hot reloading for component development.

styleguidist server [options]

Options:
  --config <path>    Path to configuration file
  --port <number>    Port number for the development server
  --open             Open styleguide in default browser automatically
  --verbose          Print detailed server information

Usage Examples:

# Start server with default config and port (6060)
styleguidist server

# Start server on custom port
styleguidist server --port 8080

# Start server and open browser automatically
styleguidist server --open

# Start server with custom config
styleguidist server --config ./dev-styleguide.config.js

# Start server with verbose logging
styleguidist server --verbose

# Combine multiple options
styleguidist server --port 3000 --open --verbose

Example npm scripts:

{
  "scripts": {
    "styleguide:dev": "styleguidist server",
    "styleguide:dev:open": "styleguidist server --open",
    "styleguide:dev:debug": "styleguidist server --verbose --port 9000",
    "styleguide:dev:custom": "styleguidist server --config configs/dev.config.js --open"
  }
}

Help Command

Display usage information and available commands.

styleguidist help
# or
styleguidist --help
# or
styleguidist

Output:

Usage

    styleguidist <command> [<options>]

Commands

    build           Build style guide
    server          Run development server
    help            Display React Styleguidist help

Options

    --config        Config file path
    --port          Port to run development server on
    --open          Open Styleguidist in the default browser
    --verbose       Print debug information

Configuration File Discovery

The CLI automatically discovers configuration files in the following order:

  1. Path specified via --config option
  2. styleguide.config.js in current directory
  3. Default configuration (if no file found)

Configuration file formats supported:

// styleguide.config.js - CommonJS
module.exports = {
  components: 'src/components/**/*.{js,jsx}',
  styleguideDir: 'dist/styleguide'
};

// styleguide.config.js - ESM (with .mjs extension or "type": "module")
export default {
  components: 'src/components/**/*.{js,jsx}',
  styleguideDir: 'dist/styleguide'
};

Environment Variables

The CLI respects several environment variables:

NODE_ENV=production    # Affects webpack optimizations and defaults
PORT=8080             # Default port if --port not specified (server command)
BROWSER=firefox       # Browser for --open option (server command)

Usage Examples:

# Production build
NODE_ENV=production styleguidist build

# Development server with custom browser
BROWSER=chrome styleguidist server --open

# Server with environment port
PORT=9090 styleguidist server

Integration Patterns

CI/CD Pipeline Integration

# GitHub Actions example
name: Build Styleguide
on: [push]
jobs:
  styleguide:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
      - run: npm ci
      - run: npx styleguidist build --verbose
      - uses: actions/upload-artifact@v2
        with:
          name: styleguide
          path: styleguide/

Docker Integration

# Dockerfile for styleguide development
FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
EXPOSE 6060
CMD ["npx", "styleguidist", "server", "--port", "6060"]

Development Workflow

# Start development with file watching
styleguidist server --open &
DEV_PID=$!

# Build for testing
styleguidist build

# Cleanup
kill $DEV_PID

Package.json Scripts Organization

{
  "scripts": {
    // Development
    "dev": "styleguidist server --open",
    "dev:verbose": "styleguidist server --verbose",
    
    // Building
    "build": "styleguidist build",
    "build:verbose": "styleguidist build --verbose",
    "prebuild": "rm -rf styleguide",
    
    // Testing
    "test:styleguide": "npm run build && serve -s styleguide -p 8080",
    
    // Deployment
    "deploy:styleguide": "npm run build && aws s3 sync styleguide/ s3://my-styleguide-bucket/",
    
    // Combined workflows
    "dev:full": "concurrently \"npm run dev\" \"npm run test:watch\"",
    "ci:styleguide": "npm run build && npm run test:styleguide"
  }
}

Error Handling

The CLI provides detailed error messages for common issues:

Configuration Errors:

$ styleguidist build --config missing.js
Error: Styleguidist config not found: /path/to/missing.js

Learn how to configure your style guide:
https://react-styleguidist.js.org/docs/configuration

Port Conflicts:

$ styleguidist server --port 3000
Error: Another server is running at port 3000 already. Please stop it or change the default port to continue.

Webpack Errors:

$ styleguidist build --verbose
Failed to compile

Module not found: Can't resolve './NonExistentComponent' in '/src/components'

Advanced CLI Usage

Custom Configuration with Environment Variables:

# Use different configs per environment
STYLEGUIDE_ENV=development styleguidist server --config configs/styleguide.${STYLEGUIDE_ENV}.js

# Override specific config values
COMPONENTS_PATTERN="src/**/*.tsx" styleguidist build

Programmatic CLI Usage:

const { spawn } = require('child_process');

function buildStyleguide(options = {}) {
  const args = ['build'];
  if (options.config) args.push('--config', options.config);
  if (options.verbose) args.push('--verbose');
  
  return new Promise((resolve, reject) => {
    const child = spawn('styleguidist', args, { stdio: 'inherit' });
    child.on('close', (code) => {
      if (code === 0) resolve();
      else reject(new Error(`CLI exited with code ${code}`));
    });
  });
}

Install with Tessl CLI

npx tessl i tessl/npm-react-styleguidist

docs

cli-commands.md

configuration.md

index.md

programmatic-api.md

webpack-integration.md

tile.json