0
# Configuration
1

2
Comprehensive configuration system for customizing React Styleguidist behavior including component discovery, webpack integration, UI theming, server settings, and build output.
3

4
## Capabilities
5

6
### Configuration Loading
7

8
Configuration can be provided through multiple methods with automatic discovery.
9

10
```typescript { .api }
11
/**
12
 * Configuration object with all optional properties
13
 */
14
interface StyleguidistConfig {
15
  components?: string | string[] | (() => string[]);
16
  sections?: ConfigSection[];
17
  webpackConfig?: webpack.Configuration | ((env?: string) => webpack.Configuration);
18
  styleguideDir?: string;
19
  serverHost?: string;
20
  serverPort?: number;
21
  theme?: RecursivePartial<Theme> | string;
22
  styles?: Styles | string | ((theme: Theme) => Styles);
23
  // ... extensive additional options
24
}
25

26
/**
27
 * Load configuration from file or object
28
 * @param config - Config object, file path, or undefined for auto-discovery
29
 * @returns Processed configuration with defaults applied
30
 */
31
function getConfig(
32
  config?: string | StyleguidistConfig,
33
  update?: (conf: StyleguidistConfig) => StyleguidistConfig
34
): SanitizedStyleguidistConfig;
35
```
36

37
**Configuration File Examples:**
38

39
```javascript
40
// styleguide.config.js
41
module.exports = {
42
  components: 'src/components/**/*.{js,jsx,ts,tsx}',
43
  styleguideDir: 'dist/styleguide',
44
  serverPort: 8080,
45
  title: 'My Component Library'
46
};
47

48
// With function-based components discovery
49
module.exports = {
50
  components: () => {
51
    const glob = require('glob');
52
    return glob.sync('src/components/**/[A-Z]*.{js,jsx}')
53
      .filter(path => !path.includes('.test.'));
54
  }
55
};
56

57
// Environment-specific configuration
58
const isDev = process.env.NODE_ENV === 'development';
59

60
module.exports = {
61
  components: 'src/components/**/*.jsx',
62
  styleguideDir: isDev ? 'tmp/styleguide' : 'dist/styleguide',
63
  serverPort: isDev ? 6060 : 8080,
64
  showCode: isDev
65
};
66
```
67

68
### Component Discovery
69

70
Configure how React Styleguidist finds and processes your components.
71

72
```typescript { .api }
73
interface ComponentConfig {
74
  /** Component file patterns or function returning file paths */
75
  components?: string | string[] | (() => string[]);
76
  
77
  /** Files/directories to ignore during component discovery */
78
  ignore?: string[];
79
  
80
  /** Skip components that don't have example files */
81
  skipComponentsWithoutExample?: boolean;
82
  
83
  /** Default example content or file path for components without examples */
84
  defaultExample?: string | boolean;
85
  
86
  /** Function to generate example file path for a component */
87
  getExampleFilename?: (componentPath: string) => string;
88
}
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
module.exports = {
95
  // Single pattern
96
  components: 'src/components/**/*.jsx',
97
  
98
  // Multiple patterns
99
  components: [
100
    'src/components/**/*.jsx',
101
    'src/widgets/**/*.jsx'
102
  ],
103
  
104
  // Function-based discovery
105
  components: () => {
106
    const glob = require('glob');
107
    return glob.sync('src/**/*.jsx')
108
      .filter(path => !path.includes('__tests__'))
109
      .filter(path => path.includes('Component'));
110
  },
111
  
112
  // Ignore patterns
113
  ignore: [
114
    '**/__tests__/**',
115
    '**/node_modules/**',
116
    '**/*.test.{js,jsx}'
117
  ],
118
  
119
  // Skip components without examples
120
  skipComponentsWithoutExample: true,
121
  
122
  // Default example for components
123
  defaultExample: 'Readme.md',
124
  // or provide default content
125
  defaultExample: '## Examples\n\n```jsx\n<ComponentName />\n```',
126
  
127
  // Custom example filename generation
128
  getExampleFilename: (componentPath) => {
129
    return componentPath.replace(/\.jsx?$/, '.examples.md');
130
  }
131
};
132
```
133

134
### Section Configuration
135

136
Organize components into logical sections and subsections.
137

138
```typescript { .api }
139
interface ConfigSection {
140
  /** Section name displayed in navigation */
141
  name?: string;
142
  
143
  /** Markdown content for section introduction */
144
  content?: string;
145
  
146
  /** Component patterns specific to this section */
147
  components?: string | string[] | (() => string[]);
148
  
149
  /** Nested subsections */
150
  sections?: ConfigSection[];
151
  
152
  /** Section description */
153
  description?: string;
154
  
155
  /** Default expand mode for examples in this section */
156
  exampleMode?: ExpandMode;
157
  
158
  /** Default expand mode for usage/props in this section */
159
  usageMode?: ExpandMode;
160
}
161

162
type ExpandMode = 'expand' | 'collapse' | 'hide';
163
```
164

165
**Usage Examples:**
166

167
```javascript
168
module.exports = {
169
  sections: [
170
    {
171
      name: 'Introduction',
172
      content: 'docs/introduction.md'
173
    },
174
    {
175
      name: 'UI Components',
176
      components: 'src/components/ui/**/*.jsx',
177
      exampleMode: 'expand',
178
      usageMode: 'collapse'
179
    },
180
    {
181
      name: 'Layout',
182
      sections: [
183
        {
184
          name: 'Grid System',
185
          components: 'src/components/layout/Grid*.jsx'
186
        },
187
        {
188
          name: 'Containers',
189
          components: 'src/components/layout/Container*.jsx'
190
        }
191
      ]
192
    },
193
    {
194
      name: 'Forms',
195
      content: 'docs/forms.md',
196
      components: () => {
197
        return [
198
          'src/components/forms/Input.jsx',
199
          'src/components/forms/Button.jsx',
200
          'src/components/forms/Form.jsx'
201
        ];
202
      }
203
    }
204
  ]
205
};
206
```
207

208
### Webpack Integration
209

210
Customize webpack configuration for component processing and bundling.
211

212
```typescript { .api }
213
interface WebpackConfig {
214
  /** Base webpack configuration or function returning config */
215
  webpackConfig?: webpack.Configuration | ((env?: string) => webpack.Configuration);
216
  
217
  /** Function to safely update generated webpack config */
218
  updateWebpackConfig?: (config: webpack.Configuration) => webpack.Configuration;
219
  
220
  /** Function to modify webpack config (use with caution) */
221
  dangerouslyUpdateWebpackConfig?: (config: webpack.Configuration, env: string) => webpack.Configuration;
222
  
223
  /** Module aliases for webpack resolution */
224
  moduleAliases?: Record<string, string>;
225
  
226
  /** Additional modules to require before rendering components */
227
  require?: string[];
228
  
229
  /** Context object available in examples */
230
  context?: Record<string, any>;
231
  
232
  /** Additional context dependencies for webpack watching */
233
  contextDependencies?: string[];
234
}
235
```
236

237
**Usage Examples:**
238

239
```javascript
240
const path = require('path');
241

242
module.exports = {
243
  // Use existing webpack config
244
  webpackConfig: require('./webpack.config.js'),
245
  
246
  // Function-based webpack config
247
  webpackConfig: (env) => {
248
    return {
249
      module: {
250
        rules: [
251
          {
252
            test: /\.scss$/,
253
            use: ['style-loader', 'css-loader', 'sass-loader']
254
          }
255
        ]
256
      },
257
      resolve: {
258
        alias: {
259
          '@': path.resolve(__dirname, 'src')
260
        }
261
      }
262
    };
263
  },
264
  
265
  // Update generated config
266
  updateWebpackConfig: (config) => {
267
    // Add source maps for development
268
    config.devtool = 'eval-source-map';
269
    
270
    // Add custom plugins
271
    config.plugins.push(
272
      new webpack.DefinePlugin({
273
        STYLEGUIDE_BUILD: true
274
      })
275
    );
276
    
277
    return config;
278
  },
279
  
280
  // Module aliases
281
  moduleAliases: {
282
    '@components': path.resolve(__dirname, 'src/components'),
283
    '@utils': path.resolve(__dirname, 'src/utils')
284
  },
285
  
286
  // Global requires
287
  require: [
288
    path.resolve(__dirname, 'src/styles/global.css'),
289
    path.resolve(__dirname, 'src/setupTests.js')
290
  ],
291
  
292
  // Context for examples
293
  context: {
294
    theme: require('./src/theme'),
295
    utils: require('./src/utils')
296
  }
297
};
298
```
299

300
### UI Theming and Styling
301

302
Customize the appearance of the styleguide interface.
303

304
```typescript { .api }
305
interface ThemeConfig {
306
  /** Theme object or path to theme file */
307
  theme?: RecursivePartial<Theme> | string;
308
  
309
  /** JSS styles, file path, or function returning styles */
310
  styles?: Styles | string | ((theme: Theme) => Styles);
311
  
312
  /** Override default UI components */
313
  styleguideComponents?: Record<string, string>;
314
}
315

316
interface Theme {
317
  color: {
318
    base: string;
319
    light: string;
320
    lightest: string;
321
    link: string;
322
    linkHover: string;
323
    error: string;
324
    // ... additional color properties
325
  };
326
  fontFamily: {
327
    base: string;
328
    monospace: string;
329
  };
330
  fontSize: {
331
    base: number;
332
    text: number;
333
    small: number;
334
    h1: number;
335
    h2: number;
336
    // ... additional font sizes
337
  };
338
  // ... layout, spacing, and border properties
339
}
340
```
341

342
**Usage Examples:**
343

344
```javascript
345
module.exports = {
346
  // Custom theme object
347
  theme: {
348
    color: {
349
      link: '#007bff',
350
      linkHover: '#0056b3',
351
      base: '#333333'
352
    },
353
    fontFamily: {
354
      base: '"Inter", -apple-system, BlinkMacSystemFont, sans-serif'
355
    }
356
  },
357
  
358
  // Theme from file
359
  theme: './src/styleguide-theme.js',
360
  
361
  // Custom styles with JSS
362
  styles: {
363
    Playground: {
364
      preview: {
365
        padding: '20px',
366
        border: '1px solid #e0e0e0',
367
        borderRadius: '4px'
368
      }
369
    },
370
    ReactComponent: {
371
      tabs: {
372
        backgroundColor: '#f8f9fa'
373
      }
374
    }
375
  },
376
  
377
  // Styles from function
378
  styles: (theme) => ({
379
    Logo: {
380
      logo: {
381
        color: theme.color.base,
382
        fontSize: theme.fontSize.h2
383
      }
384
    }
385
  }),
386
  
387
  // Custom UI components
388
  styleguideComponents: {
389
    Wrapper: path.join(__dirname, 'src/styleguide/Wrapper'),
390
    StyleGuideRenderer: path.join(__dirname, 'src/styleguide/StyleGuideRenderer')
391
  }
392
};
393
```
394

395
### Server and Build Configuration
396

397
Configure development server and build output settings.
398

399
```typescript { .api }
400
interface ServerBuildConfig {
401
  /** Development server host */
402
  serverHost?: string;
403
  
404
  /** Development server port */
405
  serverPort?: number;
406
  
407
  /** Output directory for built styleguide */
408
  styleguideDir?: string;
409
  
410
  /** Static assets directories to copy */
411
  assetsDir?: string | string[];
412
  
413
  /** HTML template or template function */
414
  template?: any;
415
  
416
  /** Styleguide title */
417
  title?: string;
418
  
419
  /** Enable/disable minification in production */
420
  minimize?: boolean;
421
  
422
  /** Enable verbose logging */
423
  verbose?: boolean;
424
}
425
```
426

427
**Usage Examples:**
428

429
```javascript
430
module.exports = {
431
  // Server configuration
432
  serverHost: '0.0.0.0',
433
  serverPort: 8080,
434
  
435
  // Build configuration
436
  styleguideDir: 'dist/styleguide',
437
  title: 'My Component Library v2.0',
438
  minimize: true,
439
  
440
  // Assets
441
  assetsDir: ['src/assets', 'public/images'],
442
  
443
  // Custom HTML template
444
  template: {
445
    favicon: 'favicon.ico',
446
    head: {
447
      meta: [
448
        { name: 'description', content: 'Component documentation' }
449
      ],
450
      links: [
451
        { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css?family=Inter' }
452
      ]
453
    }
454
  }
455
};
456
```
457

458
### Component Processing Configuration
459

460
Customize how component props and documentation are extracted and processed.
461

462
```typescript { .api }
463
interface ComponentProcessingConfig {
464
  /** Custom props parser function */
465
  propsParser?: (
466
    filePath: string,
467
    code: string,
468
    resolver: Function,
469
    handlers: Handler[]
470
  ) => DocumentationObject;
471
  
472
  /** Component resolver for react-docgen */
473
  resolver?: (ast: ASTNode, parser: any) => NodePath | NodePath[];
474
  
475
  /** React-docgen handlers for component processing */
476
  handlers?: (componentPath: string) => Handler[];
477
  
478
  /** Modify extracted component documentation */
479
  updateDocs?: (docs: PropsObject, file: string) => PropsObject;
480
  
481
  /** Custom prop sorting function */
482
  sortProps?: (props: PropDescriptor[]) => PropDescriptor[];
483
  
484
  /** Transform example before processing */
485
  updateExample?: (props: any, resourcePath: string) => any;
486
}
487
```
488

489
**Usage Examples:**
490

491
```javascript
492
const { resolver } = require('react-docgen');
493

494
module.exports = {
495
  // Custom props parser
496
  propsParser: (filePath, code, resolver, handlers) => {
497
    // Custom parsing logic
498
    return require('react-docgen').parse(code, resolver, handlers);
499
  },
500
  
501
  // Custom component resolver
502
  resolver: resolver.findAllComponentDefinitions,
503
  
504
  // Custom handlers
505
  handlers: (componentPath) => {
506
    const defaultHandlers = require('react-docgen').defaultHandlers;
507
    return [
508
      ...defaultHandlers,
509
      // Add custom handler
510
      (documentation, path) => {
511
        // Custom documentation extraction
512
      }
513
    ];
514
  },
515
  
516
  // Modify extracted docs
517
  updateDocs: (docs, file) => {
518
    // Add custom metadata
519
    docs.customMetadata = {
520
      fileName: path.basename(file),
521
      lastModified: fs.statSync(file).mtime
522
    };
523
    return docs;
524
  },
525
  
526
  // Custom prop sorting
527
  sortProps: (props) => {
528
    return props.sort((a, b) => {
529
      // Required props first
530
      if (a.required && !b.required) return -1;
531
      if (!a.required && b.required) return 1;
532
      // Then alphabetical
533
      return a.name.localeCompare(b.name);
534
    });
535
  }
536
};
537
```