or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-commands.mdconfiguration.mdindex.mdprogrammatic-api.mdwebpack-integration.md
tile.json

tessl/npm-react-styleguidist

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-styleguidist@11.0.x

To install, run

npx @tessl/cli install tessl/npm-react-styleguidist@11.0.0

index.mddocs/

React Styleguidist

React Styleguidist is a comprehensive component development environment and living style guide generator for React applications. It provides hot-reloaded development servers, automatic component documentation extraction, and interactive examples, enabling teams to create isolated development environments for React components with live editing capabilities.

Package Information

  • Package Name: react-styleguidist
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install react-styleguidist

Core Imports

const styleguidist = require('react-styleguidist');

ESM:

import styleguidist from 'react-styleguidist';

For TypeScript, all types are available:

import styleguidist, { 
  StyleguidistConfig, 
  SanitizedStyleguidistConfig,
  Theme,
  ConfigSection,
  RsgComponent,
  RsgExample,
  PropsObject
} from 'react-styleguidist';

Basic Usage

const styleguidist = require('react-styleguidist');

// Initialize with configuration
const api = styleguidist({
  components: 'src/components/**/*.{js,jsx,ts,tsx}',
  styleguideDir: 'dist/styleguide'
});

// Build static styleguide
api.build((err, config, stats) => {
  if (err) {
    console.error('Build failed:', err);
  } else {
    console.log('Styleguide built successfully');
  }
});

// Start development server
api.server((err, config) => {
  if (err) {
    console.error('Server failed:', err);
  } else {
    console.log('Development server started at http://localhost:6060');
  }
});

Architecture

React Styleguidist is built around several key components:

  • Core API: Main JavaScript/Node.js API for programmatic control (build, server, makeWebpackConfig)
  • CLI Tool: Command-line interface for common operations (styleguidist build, styleguidist server)
  • Configuration System: Extensive configuration options for customizing behavior and appearance
  • Webpack Integration: Custom webpack loaders and configuration generation for component processing
  • Client Runtime: React-based web interface for viewing and interacting with components
  • Component Processing: Automatic prop extraction and documentation generation using react-docgen

Capabilities

Programmatic API

Core Node.js API for building and serving styleguides programmatically. Ideal for integration with build systems and custom workflows.

/**
 * Initialize Styleguidist API
 * @param config - Configuration object or path to config file
 * @returns API object with build, server, and makeWebpackConfig methods
 */
function styleguidist(config?: StyleguidistConfig | string): {
  build(callback: (err: Error, config: SanitizedStyleguidistConfig, stats: webpack.Stats) => void): webpack.Compiler;
  server(callback: (err: Error | undefined, config: SanitizedStyleguidistConfig) => void): { app: WebpackDevServer; compiler: webpack.Compiler };
  makeWebpackConfig(env?: 'development' | 'production' | 'none'): webpack.Configuration;
};

Programmatic API

CLI Commands

Command-line interface for common operations including building static styleguides and running development servers.

# Build static styleguide
styleguidist build [--config <config-file>] [--verbose]

# Start development server
styleguidist server [--config <config-file>] [--port <port>] [--open] [--verbose]

# Display help
styleguidist help

CLI Commands

Configuration System

Comprehensive configuration system for customizing component discovery, webpack integration, UI theming, and build behavior.

interface StyleguidistConfig {
  components?: string | string[] | (() => string[]);
  sections?: ConfigSection[];
  webpackConfig?: webpack.Configuration | ((env?: string) => webpack.Configuration);
  styleguideDir?: string;
  serverHost?: string;
  serverPort?: number;
  theme?: RecursivePartial<Theme> | string;
  styles?: Styles | string | ((theme: Theme) => Styles);
  
  // Component Processing
  assetsDir?: string | string[];
  ignore?: string[];
  skipComponentsWithoutExample?: boolean;
  defaultExample?: string | boolean;
  getExampleFilename?: (componentPath: string) => string;
  getComponentPathLine?: (componentPath: string) => string;
  
  // Build & Server Configuration  
  minimize?: boolean;
  pagePerSection?: boolean;
  previewDelay?: number;
  configDir?: string;
  mountPointId?: string;
  
  // Advanced Configuration
  compilerConfig?: TransformOptions;
  dangerouslyUpdateWebpackConfig?: (config: webpack.Configuration, env: string) => webpack.Configuration;
  updateWebpackConfig?: (config: webpack.Configuration) => webpack.Configuration;
  context?: Record<string, any>;
  contextDependencies?: string[];
  moduleAliases?: Record<string, string>;
  require?: string[];
  
  // UI Configuration
  title?: string;
  showCode?: boolean;
  showUsage?: boolean;
  showSidebar?: boolean;
  tocMode?: ExpandMode;
  exampleMode?: ExpandMode;
  usageMode?: ExpandMode;
  
  // Customization
  template?: any;
  styleguideComponents?: Record<string, string>;
  editorConfig?: {
    theme: string;
  };
  ribbon?: {
    text?: string;
    url: string;
  };
  
  // Documentation Processing
  handlers?: (componentPath: string) => Handler[];
  resolver?: (ast: ASTNode, parser: { parse: (code: string) => ASTNode }) => NodePath<any, any> | NodePath[];
  propsParser?: (filePath: string, code: string, resolver: any, handlers: Handler[]) => DocumentationObject;
  updateDocs?: (doc: PropsObject, file: string) => PropsObject;
  updateExample?: (props: any, resourcePath: string) => any;
  sortProps?: (props: PropDescriptor[]) => PropDescriptor[];
  
  // Development & Logging
  verbose?: boolean;
  logger?: {
    info(message: string): void;
    warn(message: string): void;
    debug(message: string): void;
  };
  configureServer?: (server: WebpackDevServer, env: string) => WebpackDevServer;
  printBuildInstructions?: (config: SanitizedStyleguidistConfig) => void;
  printServerInstructions?: (config: SanitizedStyleguidistConfig, options: { isHttps: boolean }) => void;
}

Configuration

Webpack Integration

Custom webpack loaders and configuration utilities for processing React components and extracting documentation.

interface StyleguidistLoaderContext extends LoaderContext<OptionsType> {
  _styleguidist: SanitizedStyleguidistConfig;
}

// Webpack loaders (applied automatically)
// - styleguide-loader: Generates main styleguide bundle
// - props-loader: Extracts component props using react-docgen  
// - examples-loader: Processes markdown examples

Webpack Integration

Core Types

interface SanitizedStyleguidistConfig {
  // All properties from StyleguidistConfig but with defaults applied and required
  components: string | string[] | (() => string[]);
  sections: ConfigSection[];
  styleguideDir: string;
  serverHost: string;
  serverPort: number;
  webpackConfig: webpack.Configuration | ((env?: string) => webpack.Configuration);
  theme: RecursivePartial<Theme>;
  styles: ((theme: Theme) => Styles) | Styles;
  
  // Core configuration with defaults
  assetsDir: string | string[];
  tocMode: ExpandMode;
  compilerConfig: TransformOptions;
  configDir: string;
  context: Record<string, any>;
  contextDependencies: string[];
  defaultExample: string | false;
  exampleMode: ExpandMode;
  usageMode: ExpandMode;
  ignore: string[];
  minimize: boolean;
  mountPointId: string;
  moduleAliases: Record<string, string>;
  pagePerSection: boolean;
  previewDelay: number;
  require: string[];
  showCode: boolean;
  showUsage: boolean;
  showSidebar: boolean;
  skipComponentsWithoutExample: boolean;
  title: string;
  verbose: boolean;
  version: string;
  
  // Functions (with implementations)
  getComponentPathLine: (componentPath: string) => string;
  getExampleFilename: (componentPath: string) => string;
  handlers: (componentPath: string) => Handler[];
  logger: {
    info(message: string): void;
    warn(message: string): void;
    debug(message: string): void;
  };
  dangerouslyUpdateWebpackConfig: (config: webpack.Configuration, env: string) => webpack.Configuration;
  updateWebpackConfig: (config: webpack.Configuration) => webpack.Configuration;
  propsParser: (filePath: string, code: string, resolver: any, handlers: Handler[]) => DocumentationObject;
  resolver: (ast: ASTNode, parser: { parse: (code: string) => ASTNode }) => NodePath<any, any> | NodePath[];
  sortProps: (props: PropDescriptor[]) => PropDescriptor[];
  updateDocs: (doc: PropsObject, file: string) => PropsObject;
  updateExample: (props: any, resourcePath: string) => any;
  configureServer: (server: WebpackDevServer, env: string) => WebpackDevServer;
  printBuildInstructions: (config: SanitizedStyleguidistConfig) => void;
  printServerInstructions: (config: SanitizedStyleguidistConfig, options: { isHttps: boolean }) => void;
}

interface ConfigSection {
  name?: string;
  content?: string;
  components?: string | string[] | (() => string[]);
  sections?: ConfigSection[];
  description?: string;
  exampleMode?: ExpandMode;
  usageMode?: ExpandMode;
}

type ExpandMode = 'expand' | 'collapse' | 'hide';

interface Theme {
  spaceFactor: number;
  space: number[];
  color: {
    base: string;
    light: string;
    lightest: string;
    link: string;
    linkHover: string;
    focus: string;
    border: string;
    name: string;
    type: string;
    error: string;
    baseBackground: string;
    codeBackground: string;
    sidebarBackground: string;
    ribbonBackground: string;
    ribbonText: string;
    // Based on default Prism theme
    codeBase: string;
    codeComment: string;
    codePunctuation: string;
    codeProperty: string;
    codeDeleted: string;
    codeString: string;
    codeInserted: string;
    codeOperator: string;
    codeKeyword: string;
    codeFunction: string;
    codeVariable: string;
  };
  fontFamily: {
    base: string[];
    monospace: string[];
  };
  fontSize: {
    base: number;
    text: number;
    small: number;
    h1: number;
    h2: number;
    h3: number;
    h4: number;
    h5: number;
    h6: number;
  };
  mq: {
    small: string;
  };
  borderRadius: number;
  maxWidth: number;
  sidebarWidth: number;
  buttonTextTransform: string;
}