0
# React Docgen TypeScript
1
2
React Docgen TypeScript is a TypeScript-based parser for extracting React component property documentation directly from TypeScript interfaces and type definitions, eliminating the need for traditional propTypes. It integrates seamlessly with React Styleguidist and other documentation tools, offering comprehensive parsing options including prop filtering, custom component name resolution, enum value extraction, and union type handling.
3
4
## Package Information
5
6
- **Package Name**: react-docgen-typescript
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev react-docgen-typescript`
10
11
## Core Imports
12
13
```typescript
14
import * as docgen from "react-docgen-typescript";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const docgen = require("react-docgen-typescript");
21
```
22
23
Specific imports:
24
25
```typescript
26
import { parse, withDefaultConfig, withCustomConfig, withCompilerOptions } from "react-docgen-typescript";
27
```
28
29
## Basic Usage
30
31
```typescript
32
import * as docgen from "react-docgen-typescript";
33
34
// Parse a file with default options
35
const componentDocs = docgen.parse("./src/MyComponent.tsx");
36
37
// Parse with custom options
38
const options = {
39
savePropValueAsString: true,
40
shouldExtractLiteralValuesFromEnum: true,
41
};
42
const docs = docgen.parse("./src/MyComponent.tsx", options);
43
44
// Create a parser with custom configuration
45
const parser = docgen.withDefaultConfig(options);
46
const multipleDocs = parser.parse(["./src/ComponentA.tsx", "./src/ComponentB.tsx"]);
47
```
48
49
## Architecture
50
51
React Docgen TypeScript is built around several key components:
52
53
- **Parser Factory Functions**: High-level functions (`parse`, `withDefaultConfig`, `withCustomConfig`) that create configured parsers
54
- **Core Parser Class**: The `Parser` class that performs the actual TypeScript AST analysis
55
- **Configuration System**: Comprehensive options for customizing parsing behavior, filtering, and output format
56
- **TypeScript Integration**: Deep integration with TypeScript compiler API for accurate type extraction
57
- **Component Detection**: Smart detection of React components including functional, class, HOC, and styled components
58
59
## Capabilities
60
61
### Quick Parsing
62
63
Simple one-line parsing for basic use cases with sensible defaults.
64
65
```typescript { .api }
66
function parse(
67
filePathOrPaths: string | string[],
68
parserOpts?: ParserOptions
69
): ComponentDoc[];
70
```
71
72
[Quick Parsing](./parsing.md)
73
74
### Parser Configuration
75
76
Create customized parsers with different TypeScript configurations and parsing options.
77
78
```typescript { .api }
79
function withDefaultConfig(parserOpts?: ParserOptions): FileParser;
80
function withCustomConfig(tsconfigPath: string, parserOpts: ParserOptions): FileParser;
81
function withCompilerOptions(
82
compilerOptions: ts.CompilerOptions,
83
parserOpts?: ParserOptions
84
): FileParser;
85
86
interface FileParser {
87
parse(filePathOrPaths: string | string[]): ComponentDoc[];
88
parseWithProgramProvider(
89
filePathOrPaths: string | string[],
90
programProvider?: () => ts.Program
91
): ComponentDoc[];
92
}
93
```
94
95
[Parser Configuration](./configuration.md)
96
97
### Component Documentation
98
99
Complete documentation extraction including props, methods, and metadata.
100
101
```typescript { .api }
102
interface ComponentDoc {
103
expression?: ts.Symbol;
104
rootExpression?: ts.Symbol;
105
displayName: string;
106
filePath: string;
107
description: string;
108
props: Props;
109
methods: Method[];
110
tags?: StringIndexedObject<string>;
111
}
112
113
interface Props extends StringIndexedObject<PropItem> {}
114
115
interface PropItem {
116
name: string;
117
required: boolean;
118
type: PropItemType;
119
description: string;
120
defaultValue: any;
121
parent?: ParentType;
122
declarations?: ParentType[];
123
tags?: {};
124
}
125
```
126
127
[Component Documentation](./component-docs.md)
128
129
### Advanced Parser API
130
131
Direct access to the core Parser class for advanced use cases requiring fine-grained control.
132
133
```typescript { .api }
134
class Parser {
135
constructor(program: ts.Program, opts: ParserOptions);
136
getComponentInfo(
137
exp: ts.Symbol,
138
source: ts.SourceFile,
139
componentNameResolver?: ComponentNameResolver,
140
customComponentTypes?: string[]
141
): ComponentDoc | null;
142
getPropsInfo(
143
propsObj: ts.Symbol,
144
defaultProps?: StringIndexedObject<string>
145
): Props;
146
extractPropsFromTypeIfStatelessComponent(type: ts.Type): ts.Symbol | null;
147
extractPropsFromTypeIfStatefulComponent(type: ts.Type): ts.Symbol | null;
148
}
149
```
150
151
[Advanced Parser API](./advanced-parser.md)
152
153
### Parser Options
154
155
Extensive configuration options for customizing parsing behavior, filtering, and output format.
156
157
```typescript { .api }
158
interface ParserOptions {
159
propFilter?: StaticPropFilter | PropFilter;
160
componentNameResolver?: ComponentNameResolver;
161
shouldExtractLiteralValuesFromEnum?: boolean;
162
shouldRemoveUndefinedFromOptional?: boolean;
163
shouldExtractValuesFromUnion?: boolean;
164
shouldSortUnions?: boolean;
165
skipChildrenPropWithoutDoc?: boolean;
166
savePropValueAsString?: boolean;
167
shouldIncludePropTagMap?: boolean;
168
shouldIncludeExpression?: boolean;
169
customComponentTypes?: string[];
170
}
171
```
172
173
[Parser Options](./parser-options.md)
174
175
## Utility Functions
176
177
### Default Export Helper
178
179
Generates default export names based on file names.
180
181
```typescript { .api }
182
function getDefaultExportForFile(source: ts.SourceFile): string;
183
```
184
185
## Core Types
186
187
```typescript { .api }
188
interface PropItemType {
189
name: string;
190
value?: any;
191
raw?: string;
192
}
193
194
interface Method {
195
name: string;
196
docblock: string;
197
modifiers: string[];
198
params: MethodParameter[];
199
returns?: {
200
description?: string | null;
201
type?: string;
202
} | null;
203
description: string;
204
}
205
206
interface MethodParameter {
207
name: string;
208
description?: string | null;
209
type: MethodParameterType;
210
}
211
212
interface MethodParameterType {
213
name: string;
214
}
215
216
interface ParentType {
217
name: string;
218
fileName: string;
219
}
220
221
interface StringIndexedObject<T> {
222
[key: string]: T;
223
}
224
225
type PropFilter = (props: PropItem, component: Component) => boolean;
226
227
type ComponentNameResolver = (
228
exp: ts.Symbol,
229
source: ts.SourceFile
230
) => string | undefined | null | false;
231
```