0
# React Styleguidist
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: react-styleguidist
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install react-styleguidist`
10

11
## Core Imports
12

13
```javascript
14
const styleguidist = require('react-styleguidist');
15
```
16

17
ESM:
18

19
```javascript
20
import styleguidist from 'react-styleguidist';
21
```
22

23
For TypeScript, all types are available:
24

25
```typescript
26
import styleguidist, { 
27
  StyleguidistConfig, 
28
  SanitizedStyleguidistConfig,
29
  Theme,
30
  ConfigSection,
31
  RsgComponent,
32
  RsgExample,
33
  PropsObject
34
} from 'react-styleguidist';
35
```
36

37
## Basic Usage
38

39
```javascript
40
const styleguidist = require('react-styleguidist');
41

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

48
// Build static styleguide
49
api.build((err, config, stats) => {
50
  if (err) {
51
    console.error('Build failed:', err);
52
  } else {
53
    console.log('Styleguide built successfully');
54
  }
55
});
56

57
// Start development server
58
api.server((err, config) => {
59
  if (err) {
60
    console.error('Server failed:', err);
61
  } else {
62
    console.log('Development server started at http://localhost:6060');
63
  }
64
});
65
```
66

67
## Architecture
68

69
React Styleguidist is built around several key components:
70

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

78
## Capabilities
79

80
### Programmatic API
81

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

84
```javascript { .api }
85
/**
86
 * Initialize Styleguidist API
87
 * @param config - Configuration object or path to config file
88
 * @returns API object with build, server, and makeWebpackConfig methods
89
 */
90
function styleguidist(config?: StyleguidistConfig | string): {
91
  build(callback: (err: Error, config: SanitizedStyleguidistConfig, stats: webpack.Stats) => void): webpack.Compiler;
92
  server(callback: (err: Error | undefined, config: SanitizedStyleguidistConfig) => void): { app: WebpackDevServer; compiler: webpack.Compiler };
93
  makeWebpackConfig(env?: 'development' | 'production' | 'none'): webpack.Configuration;
94
};
95
```
96

97
[Programmatic API](./programmatic-api.md)
98

99
### CLI Commands
100

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

103
```bash { .api }
104
# Build static styleguide
105
styleguidist build [--config <config-file>] [--verbose]
106

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

110
# Display help
111
styleguidist help
112
```
113

114
[CLI Commands](./cli-commands.md)
115

116
### Configuration System
117

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

120
```typescript { .api }
121
interface StyleguidistConfig {
122
  components?: string | string[] | (() => string[]);
123
  sections?: ConfigSection[];
124
  webpackConfig?: webpack.Configuration | ((env?: string) => webpack.Configuration);
125
  styleguideDir?: string;
126
  serverHost?: string;
127
  serverPort?: number;
128
  theme?: RecursivePartial<Theme> | string;
129
  styles?: Styles | string | ((theme: Theme) => Styles);
130
  
131
  // Component Processing
132
  assetsDir?: string | string[];
133
  ignore?: string[];
134
  skipComponentsWithoutExample?: boolean;
135
  defaultExample?: string | boolean;
136
  getExampleFilename?: (componentPath: string) => string;
137
  getComponentPathLine?: (componentPath: string) => string;
138
  
139
  // Build & Server Configuration  
140
  minimize?: boolean;
141
  pagePerSection?: boolean;
142
  previewDelay?: number;
143
  configDir?: string;
144
  mountPointId?: string;
145
  
146
  // Advanced Configuration
147
  compilerConfig?: TransformOptions;
148
  dangerouslyUpdateWebpackConfig?: (config: webpack.Configuration, env: string) => webpack.Configuration;
149
  updateWebpackConfig?: (config: webpack.Configuration) => webpack.Configuration;
150
  context?: Record<string, any>;
151
  contextDependencies?: string[];
152
  moduleAliases?: Record<string, string>;
153
  require?: string[];
154
  
155
  // UI Configuration
156
  title?: string;
157
  showCode?: boolean;
158
  showUsage?: boolean;
159
  showSidebar?: boolean;
160
  tocMode?: ExpandMode;
161
  exampleMode?: ExpandMode;
162
  usageMode?: ExpandMode;
163
  
164
  // Customization
165
  template?: any;
166
  styleguideComponents?: Record<string, string>;
167
  editorConfig?: {
168
    theme: string;
169
  };
170
  ribbon?: {
171
    text?: string;
172
    url: string;
173
  };
174
  
175
  // Documentation Processing
176
  handlers?: (componentPath: string) => Handler[];
177
  resolver?: (ast: ASTNode, parser: { parse: (code: string) => ASTNode }) => NodePath<any, any> | NodePath[];
178
  propsParser?: (filePath: string, code: string, resolver: any, handlers: Handler[]) => DocumentationObject;
179
  updateDocs?: (doc: PropsObject, file: string) => PropsObject;
180
  updateExample?: (props: any, resourcePath: string) => any;
181
  sortProps?: (props: PropDescriptor[]) => PropDescriptor[];
182
  
183
  // Development & Logging
184
  verbose?: boolean;
185
  logger?: {
186
    info(message: string): void;
187
    warn(message: string): void;
188
    debug(message: string): void;
189
  };
190
  configureServer?: (server: WebpackDevServer, env: string) => WebpackDevServer;
191
  printBuildInstructions?: (config: SanitizedStyleguidistConfig) => void;
192
  printServerInstructions?: (config: SanitizedStyleguidistConfig, options: { isHttps: boolean }) => void;
193
}
194
```
195

196
[Configuration](./configuration.md)
197

198
### Webpack Integration
199

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

202
```typescript { .api }
203
interface StyleguidistLoaderContext extends LoaderContext<OptionsType> {
204
  _styleguidist: SanitizedStyleguidistConfig;
205
}
206

207
// Webpack loaders (applied automatically)
208
// - styleguide-loader: Generates main styleguide bundle
209
// - props-loader: Extracts component props using react-docgen  
210
// - examples-loader: Processes markdown examples
211
```
212

213
[Webpack Integration](./webpack-integration.md)
214

215
## Core Types
216

217
```typescript { .api }
218
interface SanitizedStyleguidistConfig {
219
  // All properties from StyleguidistConfig but with defaults applied and required
220
  components: string | string[] | (() => string[]);
221
  sections: ConfigSection[];
222
  styleguideDir: string;
223
  serverHost: string;
224
  serverPort: number;
225
  webpackConfig: webpack.Configuration | ((env?: string) => webpack.Configuration);
226
  theme: RecursivePartial<Theme>;
227
  styles: ((theme: Theme) => Styles) | Styles;
228
  
229
  // Core configuration with defaults
230
  assetsDir: string | string[];
231
  tocMode: ExpandMode;
232
  compilerConfig: TransformOptions;
233
  configDir: string;
234
  context: Record<string, any>;
235
  contextDependencies: string[];
236
  defaultExample: string | false;
237
  exampleMode: ExpandMode;
238
  usageMode: ExpandMode;
239
  ignore: string[];
240
  minimize: boolean;
241
  mountPointId: string;
242
  moduleAliases: Record<string, string>;
243
  pagePerSection: boolean;
244
  previewDelay: number;
245
  require: string[];
246
  showCode: boolean;
247
  showUsage: boolean;
248
  showSidebar: boolean;
249
  skipComponentsWithoutExample: boolean;
250
  title: string;
251
  verbose: boolean;
252
  version: string;
253
  
254
  // Functions (with implementations)
255
  getComponentPathLine: (componentPath: string) => string;
256
  getExampleFilename: (componentPath: string) => string;
257
  handlers: (componentPath: string) => Handler[];
258
  logger: {
259
    info(message: string): void;
260
    warn(message: string): void;
261
    debug(message: string): void;
262
  };
263
  dangerouslyUpdateWebpackConfig: (config: webpack.Configuration, env: string) => webpack.Configuration;
264
  updateWebpackConfig: (config: webpack.Configuration) => webpack.Configuration;
265
  propsParser: (filePath: string, code: string, resolver: any, handlers: Handler[]) => DocumentationObject;
266
  resolver: (ast: ASTNode, parser: { parse: (code: string) => ASTNode }) => NodePath<any, any> | NodePath[];
267
  sortProps: (props: PropDescriptor[]) => PropDescriptor[];
268
  updateDocs: (doc: PropsObject, file: string) => PropsObject;
269
  updateExample: (props: any, resourcePath: string) => any;
270
  configureServer: (server: WebpackDevServer, env: string) => WebpackDevServer;
271
  printBuildInstructions: (config: SanitizedStyleguidistConfig) => void;
272
  printServerInstructions: (config: SanitizedStyleguidistConfig, options: { isHttps: boolean }) => void;
273
}
274

275
interface ConfigSection {
276
  name?: string;
277
  content?: string;
278
  components?: string | string[] | (() => string[]);
279
  sections?: ConfigSection[];
280
  description?: string;
281
  exampleMode?: ExpandMode;
282
  usageMode?: ExpandMode;
283
}
284

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

287
interface Theme {
288
  spaceFactor: number;
289
  space: number[];
290
  color: {
291
    base: string;
292
    light: string;
293
    lightest: string;
294
    link: string;
295
    linkHover: string;
296
    focus: string;
297
    border: string;
298
    name: string;
299
    type: string;
300
    error: string;
301
    baseBackground: string;
302
    codeBackground: string;
303
    sidebarBackground: string;
304
    ribbonBackground: string;
305
    ribbonText: string;
306
    // Based on default Prism theme
307
    codeBase: string;
308
    codeComment: string;
309
    codePunctuation: string;
310
    codeProperty: string;
311
    codeDeleted: string;
312
    codeString: string;
313
    codeInserted: string;
314
    codeOperator: string;
315
    codeKeyword: string;
316
    codeFunction: string;
317
    codeVariable: string;
318
  };
319
  fontFamily: {
320
    base: string[];
321
    monospace: string[];
322
  };
323
  fontSize: {
324
    base: number;
325
    text: number;
326
    small: number;
327
    h1: number;
328
    h2: number;
329
    h3: number;
330
    h4: number;
331
    h5: number;
332
    h6: number;
333
  };
334
  mq: {
335
    small: string;
336
  };
337
  borderRadius: number;
338
  maxWidth: number;
339
  sidebarWidth: number;
340
  buttonTextTransform: string;
341
}
342
```