0
# Parser Configuration
1

2
Advanced parser configuration for customizing TypeScript compiler options and creating reusable parser instances with specific configurations.
3

4
## Capabilities
5

6
### Default Configuration Parser
7

8
Creates a parser with default TypeScript configuration and custom parsing options.
9

10
```typescript { .api }
11
/**
12
 * Constructs a parser for a default configuration
13
 * @param parserOpts - Parser options for customizing behavior
14
 * @returns FileParser instance with default TypeScript config
15
 */
16
function withDefaultConfig(parserOpts: ParserOptions = defaultParserOpts): FileParser;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { withDefaultConfig } from "react-docgen-typescript";
23

24
// Create parser with custom options
25
const parser = withDefaultConfig({
26
  propFilter: {
27
    skipPropsWithName: ['className', 'style'],
28
    skipPropsWithoutDoc: true
29
  },
30
  shouldExtractLiteralValuesFromEnum: true
31
});
32

33
// Use the parser multiple times
34
const buttonDocs = parser.parse("./src/Button.tsx");
35
const inputDocs = parser.parse("./src/Input.tsx");
36
```
37

38
### Custom TypeScript Configuration Parser
39

40
Creates a parser using a specific tsconfig.json file for TypeScript compilation.
41

42
```typescript { .api }
43
/**
44
 * Constructs a parser for a specified tsconfig file
45
 * @param tsconfigPath - Path to tsconfig.json file
46
 * @param parserOpts - Parser options for customizing behavior
47
 * @returns FileParser instance with custom TypeScript config
48
 * @throws Error when tsconfig cannot be loaded or parsed
49
 */
50
function withCustomConfig(
51
  tsconfigPath: string,
52
  parserOpts: ParserOptions
53
): FileParser;
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { withCustomConfig } from "react-docgen-typescript";
60

61
// Use project's tsconfig.json
62
const parser = withCustomConfig("./tsconfig.json", {
63
  savePropValueAsString: true
64
});
65

66
// Use specific tsconfig for documentation
67
const parser = withCustomConfig("./tsconfig.docs.json", {
68
  shouldExtractValuesFromUnion: true,
69
  componentNameResolver: (exp, source) => {
70
    // Custom component name resolution logic
71
    return exp.getName() === "default" ? "MyComponent" : exp.getName();
72
  }
73
});
74

75
const docs = parser.parse("./src/components/*.tsx");
76
```
77

78
### Compiler Options Parser
79

80
Creates a parser with explicit TypeScript compiler options.
81

82
```typescript { .api }
83
/**
84
 * Constructs a parser for a specified set of TS compiler options
85
 * @param compilerOptions - TypeScript compiler options
86
 * @param parserOpts - Parser options for customizing behavior
87
 * @returns FileParser instance with specified compiler options
88
 */
89
function withCompilerOptions(
90
  compilerOptions: ts.CompilerOptions,
91
  parserOpts: ParserOptions = defaultParserOpts
92
): FileParser;
93
```
94

95
**Usage Examples:**
96

97
```typescript
98
import { withCompilerOptions } from "react-docgen-typescript";
99
import * as ts from "typescript";
100

101
// Custom compiler options
102
const parser = withCompilerOptions(
103
  {
104
    jsx: ts.JsxEmit.ReactJSX,
105
    target: ts.ScriptTarget.ES2020,
106
    moduleResolution: ts.ModuleResolutionKind.NodeJs,
107
    strict: true,
108
    esModuleInterop: true
109
  },
110
  {
111
    shouldExtractLiteralValuesFromEnum: true,
112
    shouldSortUnions: true
113
  }
114
);
115

116
const docs = parser.parse("./src/ModernComponent.tsx");
117
```
118

119
### FileParser Interface
120

121
The parser interface returned by configuration functions.
122

123
```typescript { .api }
124
interface FileParser {
125
  /**
126
   * Parse component files and return documentation
127
   * @param filePathOrPaths - Single file path or array of paths
128
   * @returns Array of component documentation
129
   */
130
  parse(filePathOrPaths: string | string[]): ComponentDoc[];
131
  
132
  /**
133
   * Parse with custom TypeScript program provider
134
   * @param filePathOrPaths - Single file path or array of paths  
135
   * @param programProvider - Function that returns TypeScript Program
136
   * @returns Array of component documentation
137
   */
138
  parseWithProgramProvider(
139
    filePathOrPaths: string | string[],
140
    programProvider?: () => ts.Program
141
  ): ComponentDoc[];
142
}
143
```
144

145
## Advanced Configuration Patterns
146

147
### Shared Parser Instance
148

149
```typescript
150
import { withDefaultConfig } from "react-docgen-typescript";
151

152
// Create shared parser for consistent configuration
153
const sharedParser = withDefaultConfig({
154
  propFilter: {
155
    skipPropsWithName: ['className', 'style', 'children'],
156
    skipPropsWithoutDoc: true
157
  },
158
  shouldExtractLiteralValuesFromEnum: true,
159
  savePropValueAsString: true
160
});
161

162
// Use across multiple parsing operations
163
const componentDocs = [
164
  ...sharedParser.parse("./src/components/Button.tsx"),
165
  ...sharedParser.parse("./src/components/Input.tsx"),
166
  ...sharedParser.parse("./src/components/Modal.tsx")
167
];
168
```
169

170
### TypeScript Program Reuse
171

172
```typescript
173
import { withCompilerOptions } from "react-docgen-typescript";
174
import * as ts from "typescript";
175

176
const compilerOptions = {
177
  jsx: ts.JsxEmit.React,
178
  target: ts.ScriptTarget.ES2019,
179
  moduleResolution: ts.ModuleResolutionKind.NodeJs
180
};
181

182
const parser = withCompilerOptions(compilerOptions);
183

184
// Create TypeScript program once for multiple parses
185
const filePaths = ["./src/Button.tsx", "./src/Input.tsx"];
186
const program = ts.createProgram(filePaths, compilerOptions);
187

188
const docs = parser.parseWithProgramProvider(filePaths, () => program);
189
```
190

191
## Error Handling
192

193
Configuration functions can throw errors in several scenarios:
194

195
```typescript
196
import { withCustomConfig } from "react-docgen-typescript";
197

198
try {
199
  const parser = withCustomConfig("./invalid-tsconfig.json", {});
200
} catch (error) {
201
  // Handle configuration errors
202
  if (error.message.includes("Cannot load custom tsconfig.json")) {
203
    console.error("Invalid tsconfig path:", error.message);
204
  }
205
}
206
```
207

208
Common error scenarios:
209

210
- **Invalid tsconfig.json path**: File doesn't exist or isn't readable
211
- **Malformed tsconfig.json**: Invalid JSON or TypeScript configuration
212
- **TypeScript compilation errors**: Invalid compiler options or project setup