0
# Configuration
1

2
Configuration system for customizing parsing behavior and analysis options in react-docgen.
3

4
## Capabilities
5

6
### Config Interface
7

8
The main configuration interface for customizing the parsing process.
9

10
```typescript { .api }
11
interface Config {
12
  /** Array of handlers to process component information */
13
  handlers?: Handler[];
14
  /** Importer for resolving module dependencies */
15
  importer?: Importer;
16
  /** Resolver for finding component definitions */
17
  resolver?: Resolver;
18
  /** Filename for the code being parsed (affects import resolution) */
19
  filename?: string;
20
  /** Babel parser configuration options */
21
  babelOptions?: TransformOptions;
22
}
23
```
24

25
### Internal Configuration Type
26

27
The internal configuration type used by the parser after applying defaults.
28

29
```typescript { .api }
30
type InternalConfig = Omit<Required<Config>, 'filename'>;
31
```
32

33
**Note:** Configuration objects are automatically processed by the `parse` function. You don't need to call any configuration factory functions directly.
34

35
### Default Configuration
36

37
Default configuration values used when options are not specified.
38

39
```typescript { .api }
40
/** Default array of handlers covering all common use cases */
41
const defaultHandlers: Handler[];
42

43
/** Default resolver for finding exported and annotated components */
44
const defaultResolver: Resolver;
45

46
/** Default importer using filesystem resolution */
47
const defaultImporter: Importer;
48
```
49

50
**Default Handler Stack:**
51
1. `propTypeHandler` - Extract PropTypes definitions
52
2. `contextTypeHandler` - Extract context types
53
3. `childContextTypeHandler` - Extract child context types
54
4. `propTypeCompositionHandler` - Handle prop composition patterns
55
5. `propDocblockHandler` - Extract prop JSDoc comments
56
6. `codeTypeHandler` - Extract TypeScript/Flow type information
57
7. `defaultPropsHandler` - Extract default prop values
58
8. `componentDocblockHandler` - Extract component JSDoc comments
59
9. `displayNameHandler` - Extract component display names
60
10. `componentMethodsHandler` - Extract component methods
61
11. `componentMethodsJsDocHandler` - Extract method JSDoc comments
62

63
### Handler Configuration
64

65
Customizing the information extraction process with custom handlers.
66

67
```typescript { .api }
68
import { parse, defaultHandlers, Handler } from "react-docgen";
69

70
// Using subset of default handlers
71
const docs = parse(sourceCode, {
72
  handlers: [
73
    propTypeHandler,
74
    displayNameHandler,
75
    componentDocblockHandler
76
  ]
77
});
78

79
// Adding custom handlers to defaults
80
const customHandler: Handler = (documentation, componentDefinition) => {
81
  // Custom extraction logic
82
};
83

84
const docsWithCustom = parse(sourceCode, {
85
  handlers: [...defaultHandlers, customHandler]
86
});
87
```
88

89
### Resolver Configuration
90

91
Customizing component discovery with different resolver strategies.
92

93
```typescript { .api }
94
import { 
95
  parse, 
96
  builtinResolvers
97
} from "react-docgen";
98

99
// Find all components in file
100
const docs = parse(sourceCode, {
101
  resolver: new builtinResolvers.FindAllDefinitionsResolver()
102
});
103

104
// Find only exported components with limit
105
const exportedDocs = parse(sourceCode, {
106
  resolver: new builtinResolvers.FindExportedDefinitionsResolver({ limit: 1 })
107
});
108

109
// Chain multiple resolvers
110
const chainedDocs = parse(sourceCode, {
111
  resolver: new builtinResolvers.ChainResolver([
112
    new builtinResolvers.FindExportedDefinitionsResolver({ limit: 1 }),
113
    new builtinResolvers.FindAllDefinitionsResolver()
114
  ], { chainingLogic: builtinResolvers.ChainResolver.Logic.FIRST_FOUND })
115
});
116
```
117

118
### Importer Configuration
119

120
Customizing module import resolution behavior.
121

122
```typescript { .api }
123
import { 
124
  parse, 
125
  fsImporter, 
126
  ignoreImporter, 
127
  makeFsImporter 
128
} from "react-docgen";
129

130
// Ignore all imports (browser-safe)
131
const docs = parse(sourceCode, {
132
  importer: ignoreImporter
133
});
134

135
// Custom filesystem importer
136
const customImporter = makeFsImporter({
137
  extensions: ['.tsx', '.ts', '.jsx', '.js'],
138
  preserveSymlinks: false
139
});
140

141
const docsWithCustomImporter = parse(sourceCode, {
142
  importer: customImporter,
143
  filename: '/path/to/component.tsx'
144
});
145
```
146

147
### Babel Configuration
148

149
Customizing the Babel parser options for different syntax support.
150

151
```typescript { .api }
152
import { parse } from "react-docgen";
153

154
const docs = parse(sourceCode, {
155
  babelOptions: {
156
    // Parser options
157
    parserOpts: {
158
      plugins: [
159
        'jsx',
160
        'typescript',
161
        'decorators-legacy',
162
        'classProperties'
163
      ]
164
    },
165
    // Transform options  
166
    presets: [
167
      '@babel/preset-typescript',
168
      '@babel/preset-react'
169
    ]
170
  }
171
});
172
```
173

174
### Filename Configuration
175

176
Setting the filename affects import resolution and error reporting.
177

178
```typescript { .api }
179
import { parse } from "react-docgen";
180

181
// With filename for proper import resolution
182
const docs = parse(sourceCode, {
183
  filename: '/absolute/path/to/Component.tsx'
184
});
185

186
// Relative filename (relative to babelOptions.cwd)
187
const docsRelative = parse(sourceCode, {
188
  filename: 'src/Component.tsx',
189
  babelOptions: {
190
    cwd: '/project/root'
191
  }
192
});
193
```
194

195
### Complete Configuration Example
196

197
Comprehensive configuration example showing all options.
198

199
```typescript { .api }
200
import { 
201
  parse,
202
  defaultHandlers,
203
  builtinResolvers,
204
  makeFsImporter,
205
  Handler
206
} from "react-docgen";
207

208
// Custom handler for extracting additional metadata
209
const customMetadataHandler: Handler = (documentation, componentDefinition) => {
210
  // Extract custom metadata from JSDoc tags
211
  const comments = getJSDocComments(componentDefinition);
212
  const metadata = extractCustomTags(comments);
213
  documentation.set('customMetadata', metadata);
214
};
215

216
// Complete configuration
217
const docs = parse(sourceCode, {
218
  // Handler configuration
219
  handlers: [
220
    ...defaultHandlers,
221
    customMetadataHandler
222
  ],
223
  
224
  // Resolver configuration
225
  resolver: new builtinResolvers.FindExportedDefinitionsResolver({ 
226
    limit: 1 
227
  }),
228
  
229
  // Importer configuration
230
  importer: makeFsImporter({
231
    extensions: ['.tsx', '.ts', '.jsx', '.js', '.mjs'],
232
    preserveSymlinks: false
233
  }),
234
  
235
  // File context
236
  filename: '/absolute/path/to/component.tsx',
237
  
238
  // Babel configuration
239
  babelOptions: {
240
    parserOpts: {
241
      plugins: [
242
        'jsx',
243
        'typescript', 
244
        'decorators-legacy',
245
        'classProperties',
246
        'objectRestSpread',
247
        'functionBind'
248
      ]
249
    },
250
    presets: [
251
      ['@babel/preset-typescript', { 
252
        isTSX: true, 
253
        allExtensions: true 
254
      }],
255
      '@babel/preset-react'
256
    ]
257
  }
258
});
259
```
260

261
### Environment-Specific Configuration
262

263
Different configurations for different environments.
264

265
```typescript { .api }
266
import { defaultHandlers, builtinResolvers, builtinImporters } from "react-docgen";
267
// Node.js environment (full features)
268
const nodeConfig = {
269
  handlers: defaultHandlers,
270
  importer: builtinImporters.fsImporter,
271
  // Uses default resolver (exported from config, not directly available)
272
};
273

274
// Browser environment (limited imports)
275
const browserConfig = {
276
  handlers: defaultHandlers,
277
  importer: builtinImporters.ignoreImporter, // No filesystem access
278
  // Uses default resolver
279
};
280

281
// Testing environment (find all components)
282
const testConfig = {
283
  handlers: defaultHandlers,
284
  importer: builtinImporters.ignoreImporter,
285
  resolver: new builtinResolvers.FindAllDefinitionsResolver() // Find everything
286
};
287
```
288

289
### Configuration Validation
290

291
The configuration system validates inputs and provides sensible defaults.
292

293
**Validation Rules:**
294
- Unknown handler types are filtered out
295
- Invalid resolver objects default to `defaultResolver`
296
- Invalid importer functions default to `defaultImporter`
297
- Babel options are merged with safe defaults
298
- Filename paths are normalized
299

300
**Error Handling:**
301
- Invalid configurations log warnings but don't throw errors
302
- Partial configurations are completed with defaults
303
- Type mismatches are corrected automatically where possible