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