0
# React-docgen
1

2
React-docgen is a comprehensive library designed to extract structured metadata from React components for documentation generation. It analyzes React component source code using Babel parsing and AST traversal to automatically discover component properties, methods, type information, and JSDoc comments.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { parse } from "react-docgen";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { parse } = require("react-docgen");
21
```
22

23
Additional imports for advanced usage:
24

25
```typescript
26
import { 
27
  parse, 
28
  builtinHandlers, 
29
  builtinResolvers, 
30
  builtinImporters,
31
  utils,
32
  ERROR_CODES,
33
  makeFsImporter
34
} from "react-docgen";
35

36
// Type imports
37
import type { 
38
  Documentation,
39
  DocumentationBuilder,
40
  Config,
41
  Handler,
42
  Resolver,
43
  Importer,
44
  FileState,
45
  NodePath,
46
  babelTypes
47
} from "react-docgen";
48
```
49

50
## Basic Usage
51

52
```typescript
53
import { parse } from "react-docgen";
54

55
// Parse a React component
56
const componentCode = `
57
import React from 'react';
58

59
interface Props {
60
  /** The name to display */
61
  name: string;
62
  /** Whether the component is active */
63
  active?: boolean;
64
}
65

66
/**
67
 * A greeting component that displays a name
68
 */
69
export default function Greeting({ name, active = false }: Props) {
70
  return <div className={active ? 'active' : ''}>{name}</div>;
71
}
72
`;
73

74
const docs = parse(componentCode);
75
console.log(docs);
76
// Returns array of Documentation objects with props, methods, description, etc.
77
```
78

79
## Architecture
80

81
React-docgen is built around several key components:
82

83
- **Parser Core**: Main parsing function that orchestrates the analysis process
84
- **Resolver System**: Finds and identifies React component definitions in source code
85
- **Handler System**: Extracts specific information from components (props, methods, JSDoc, etc.)
86
- **Importer System**: Resolves module imports and dependencies during analysis
87
- **Documentation Builder**: Constructs structured documentation objects from extracted data
88
- **Type Analysis**: Comprehensive TypeScript and Flow type extraction utilities
89

90
## Capabilities
91

92
### Core Parsing
93

94
Main parsing functionality for extracting React component documentation from source code.
95

96
```typescript { .api }
97
function parse(src: Buffer | string, config?: Config): Documentation[];
98

99
interface Documentation {
100
  childContext?: Record<string, PropDescriptor>;
101
  composes?: string[];
102
  context?: Record<string, PropDescriptor>;
103
  description?: string;
104
  displayName?: string;
105
  methods?: MethodDescriptor[];
106
  props?: Record<string, PropDescriptor>;
107
}
108

109
class DocumentationBuilder {
110
  constructor();
111
  addComposes(moduleName: string): void;
112
  set(key: string, value: unknown): void;
113
  get<T>(key: string): T | null;
114
  getPropDescriptor(propName: string): PropDescriptor;
115
  getContextDescriptor(propName: string): PropDescriptor;
116
  getChildContextDescriptor(propName: string): PropDescriptor;
117
  build(): Documentation;
118
}
119
```
120

121
[Core Parsing](./parsing.md)
122

123
### Component Resolution
124

125
System for finding and identifying React component definitions within source files.
126

127
```typescript { .api }
128
interface FindExportedDefinitionsResolver {
129
  resolve: (file: FileState) => ComponentNodePath[];
130
}
131

132
interface FindAllDefinitionsResolver {
133
  resolve: (file: FileState) => ComponentNodePath[];
134
}
135

136
interface FindAnnotatedDefinitionsResolver {
137
  resolve: (file: FileState) => ComponentNodePath[];
138
}
139
```
140

141
[Component Resolution](./resolvers.md)
142

143
### Information Extraction
144

145
Handlers that extract specific types of information from React components.
146

147
```typescript { .api }
148
type Handler = (
149
  documentation: Documentation,
150
  componentDefinition: NodePath<ComponentNode>
151
) => void;
152
```
153

154
[Information Extraction](./handlers.md)
155

156
### Module Import Resolution
157

158
System for resolving module imports and dependencies during component analysis.
159

160
```typescript { .api }
161
type Importer = (
162
  path: ImportPath,
163
  name: string,
164
  file: FileState
165
) => NodePath | null;
166
```
167

168
[Module Import Resolution](./importers.md)
169

170
### Configuration
171

172
Configuration system for customizing parsing behavior and analysis options.
173

174
```typescript { .api }
175
interface Config {
176
  handlers?: Handler[];
177
  importer?: Importer;
178
  resolver?: Resolver;
179
  filename?: string;
180
  babelOptions?: TransformOptions;
181
}
182
```
183

184
[Configuration](./configuration.md)
185

186
### AST Analysis Utilities
187

188
Comprehensive collection of utilities for React component and TypeScript/Flow analysis.
189

190
```typescript { .api }
191
// Key utility namespaces
192
namespace utils {
193
  namespace docblock;
194
  namespace expressionTo;
195
  namespace flowUtilityTypes;  
196
  namespace traverse;
197
}
198
```
199

200
[AST Analysis Utilities](./utilities.md)
201

202
### Error Handling
203

204
Error handling system for parsing failures and validation issues.
205

206
```typescript { .api }
207
enum ERROR_CODES {
208
  MISSING_DEFINITION = 'ERR_REACTDOCGEN_MISSING_DEFINITION',
209
  MULTIPLE_DEFINITIONS = 'ERR_REACTDOCGEN_MULTIPLE_DEFINITIONS',
210
}
211
```
212

213
[Error Handling](./error-handling.md)
214

215
## Types
216

217
```typescript { .api }
218
interface PropDescriptor {
219
  type?: PropTypeDescriptor;
220
  flowType?: TypeDescriptor<FunctionSignatureType>;
221
  tsType?: TypeDescriptor<TSFunctionSignatureType>;
222
  required?: boolean;
223
  defaultValue?: DefaultValueDescriptor;
224
  description?: string;
225
}
226

227
interface MethodDescriptor {
228
  name: string;
229
  description?: string | null;
230
  docblock: string | null;
231
  modifiers: MethodModifier[];
232
  params: MethodParameter[];
233
  returns: MethodReturn | null;
234
}
235

236
interface MethodParameter {
237
  name: string;
238
  description?: string;
239
  optional: boolean;
240
  type?: TypeDescriptor<FunctionSignatureType> | null;
241
}
242

243
type ComponentNode = 
244
  | CallExpression
245
  | ClassDeclaration
246
  | ClassExpression
247
  | ObjectExpression
248
  | StatelessComponentNode;
249

250
type StatelessComponentNode =
251
  | ArrowFunctionExpression
252
  | FunctionDeclaration
253
  | FunctionExpression
254
  | ObjectMethod;
255

256
// Type aliases and interfaces
257
interface FileState {
258
  // Internal file state used by parsers and importers
259
}
260

261
type InternalConfig = Omit<Required<Config>, 'filename'>;
262

263
// Re-exported from Babel for convenience
264
type NodePath = import('@babel/traverse').NodePath;
265
type babelTypes = typeof import('@babel/types');
266
```