React Docgen TypeScript

https://github.com/styleguidist/react-docgen-typescript
Admin
React Docgen TypeScript is a parser that extracts component documentation, props, and types from...
Tokens:25,817
Snippets:204
Trust Score:8.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install react-docgen-typescript

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Install the react-docgen-typescript package as a development dependency.

```bash
npm install --save-dev react-docgen-typescript
```

--------------------------------

### Example error message for missing tsconfig

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/errors.md

An example of the error message thrown when a tsconfig file cannot be loaded.

```text
Error: Cannot load custom tsconfig.json from provided path: ./missing-tsconfig.json, with error code: 505, message: Invalid option type...
```

--------------------------------

### Basic getComponentInfo call

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Example demonstrating how to retrieve component information by mapping over module exports.

```ts
const checker = program.getTypeChecker();
const source = program.getSourceFile('/abs/src/Button.tsx');
const moduleSymbol = checker.getSymbolAtLocation(source);

const docs = checker
  .getExportsOfModule(moduleSymbol)
  .map((exp) => parser.getComponentInfo(exp, source))
  .filter((d): d is NonNullable<typeof d> => d !== null);

// docs[0].displayName, docs[0].filePath, docs[0].description,
// docs[0].props, docs[0].methods, docs[0].tags
```

--------------------------------

### Example — object filter

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/helper-modules.md

Shows how to use buildFilter with an object propFilter to skip props by name and without documentation. The example includes a standalone call that returns false for a prop named 'as'.

```typescript
import { buildFilter } from 'react-docgen-typescript/lib/buildFilter';

const keep = buildFilter({
  propFilter: { skipPropsWithName: ['as', 'id'], skipPropsWithoutDoc: true },
});

// standalone use
const prop: PropItemLike = { name: 'as', description: '', /* ... */ };
keep(prop as any, { name: 'MyComponent' } as any); // => false
```

--------------------------------

### Custom resolver and component types

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Example showing how to provide a custom component name resolver and additional component type names to the parser.

```ts
const doc = parser.getComponentInfo(
  exp,
  source,
  (exp, source) => (exp.getName() === 'StyledComponentClass' ? 'Styled' : undefined),
  ['OverridableComponent'] // extra type names recognized as components
);
```

--------------------------------

### Basic Parser construction example using ts.createProgram and parser.getComponentInfo

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Illustrates how to create a Parser with a TypeScript program and custom options, then iterate over the module's exports to extract component documentation. Requires a program created with the given compiler options (jsx, module, target, esModuleInterop) and an existing Button.tsx file. The output for each exported component logs its displayName and prop keys when a doc is found.

```typescript
import * as ts from 'typescript';
import { Parser } from 'react-docgen-typescript';

const paths = [require.resolve('./Button.tsx')];
const program = ts.createProgram(paths, {
  jsx: ts.JsxEmit.React,
  module: ts.ModuleKind.CommonJS,
  target: ts.ScriptTarget.Latest,
  esModuleInterop: true,
});

const parser = new Parser(program, { shouldExtractValuesFromUnion: true });
const checker = program.getTypeChecker();
const source = program.getSourceFile(paths[0]);
const moduleSymbol = checker.getSymbolAtLocation(source);
for (const exp of checker.getExportsOfModule(moduleSymbol)) {
  const doc = parser.getComponentInfo(exp, source);
  if (doc) console.log(doc.displayName, Object.keys(doc.props));
}

```

--------------------------------

### propTypesParser usage example

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/helper-modules.md

Shows how to require the propTypesParser module and call parse on a component file, then access the props of the first component.

```typescript
const { parse } = require('react-docgen-typescript/lib/propTypesParser');

const docs = parse('./src/components/Grid.tsx');
const propsOfFirstComponent = docs[0].props;
```

--------------------------------

### Catching configuration errors

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/errors.md

Example of how to catch and differentiate between tsconfig loading errors and TypeScript compiler option errors.

```ts
import { withCustomConfig } from 'react-docgen-typescript';

let parser;
try {
  parser = withCustomConfig('./tsconfig.json', { savePropValueAsString: true });
} catch (e) {
  if (e instanceof Error && /Cannot load custom tsconfig\.json/.test(e.message)) {
    // tsconfig missing/unparseable — fall back to default options
    console.error('tsconfig problem:', e.message);
  } else {
    // TS compiler-option error — message starts with "TS<code>:"
    console.error('compiler options problem:', e.message);
  }
}
```

--------------------------------

### trimFileName usage example

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/helper-modules.md

Shows typical usage of trimFileName with a POSIX path and a Windows path with explicit platform. The first call uses the default cwd, the second forces win32 semantics.

```typescript
import { trimFileName } from 'react-docgen-typescript/lib/trimFileName';

trimFileName('/repo/apps/web/src/Button.tsx'); // 'src/Button.tsx' (cwd = /repo/apps/web)
trimFileName('C:\\repo\\src\\Props.ts', undefined, 'win32'); // 'src\\Props.ts'
```

--------------------------------

### Setting defaultProps

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Example of setting defaultProps on a component. When savePropValueAsString is true, the defaultValue will be returned as a string.

```javascript
Component.defaultProps = {
  counter: 123,
  disabled: false,
};
```

--------------------------------

### Example - deriving a default-export name

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser.md

Shows how to use getDefaultExportForFile with a TypeScript source file created via ts.createSourceFile. The example logs 'Column' for a file named 'src/components/Column.tsx'.

```TypeScript
import * as ts from 'typescript';
import { getDefaultExportForFile } from 'react-docgen-typescript';

const source = ts.createSourceFile(
  'src/components/Column.tsx',
  'export default 1;',
  ts.ScriptTarget.Latest
);
console.log(getDefaultExportForFile(source)); // 'Column'
```

--------------------------------

### Example — destructured defaults

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Demonstrates extracting default props from a destructured function parameter.

```ts
// source: export const Row = ({ padding = 4, label = 'row' }) => <div>{label}</div>;
const defaults = parser.extractDefaultPropsFromComponent(rowSymbol, source);
// => { padding: 4, label: 'row' }
// with savePropValueAsString: true  => { padding: '4', label: 'row' }
```

--------------------------------

### Enum extraction example

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Example output of getDocgenType when extracting enum values from a union type with specific configuration options.

```ts
// prop:  /** choice */ c?: 'one' | 'two'
// options: { shouldExtractLiteralValuesFromEnum: true, shouldRemoveUndefinedFromOptional: true }
{
  name: 'enum',
  raw: '"one" | "two" | undefined',
  value: [
    { value: '"one"', description: 'choice', fullComment: 'choice', tags: {} },
    { value: '"two"', description: '', fullComment: '', tags: {} }
  ]
}
```

--------------------------------

### Example — custom function filter (README pattern)

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/helper-modules.md

Shows how to use buildFilter with a custom function propFilter that keeps props with declarations outside node_modules. This matches the README pattern.

```typescript
import { buildFilter } from 'react-docgen-typescript/lib/buildFilter';

const filter = buildFilter({
  propFilter: (prop, component) => {
    if (prop.declarations !== undefined && prop.declarations.length > 0) {
      const hasPropAdditionalDescription = prop.declarations.find((declaration) => {
        return !declaration.fileName.includes('node_modules');
      });
      return Boolean(hasPropAdditionalDescription);
    }
    return true;
  },
});
```

--------------------------------

### Output with savePropValueAsString

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Output of the defaultProps example when savePropValueAsString is true. The defaultValue is returned as a string, e.g., '123' and 'false'.

```javascript
  counter: {
      defaultValue: '123',
      required: true,
      type: 'number'
  },
  disabled: {
      defaultValue: 'false',
      required: true,
      type: 'boolean'
  }
```

--------------------------------

### Example ComponentDoc JSON shape

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/types.md

Shows the parsed output for a documented Column.tsx component, illustrating the structure of displayName, filePath, description, tags, props, and methods.

```JSON
{
  "displayName": "Column",
  "filePath": "/repo/src/Column.tsx",
  "description": "Form column.",
  "tags": {},
  "props": {
    "prop1": { "name": "prop1", "required": false, "type": { "name": "string" }, "description": "prop1 description", "defaultValue": null }
  },
  "methods": []
}
```

--------------------------------

### propFilter with pre-configured filters

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Configure the propFilter option with pre-defined filters to skip props by name or without documentation. The interface defines the shape of the filter options, and the example shows how to set skipPropsWithName and skipPropsWithoutDoc in the options object.

```typescript
interface FilterOptions {
  skipPropsWithName?: string[] | string;
  skipPropsWithoutDoc?: boolean;
}

const options = {
  propFilter: {
    skipPropsWithName: ['as', 'id'];
    skipPropsWithoutDoc: true;
  }
}
```

--------------------------------

### Component with HTMLAttributes

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Example of a component typed with React.FC and HTMLAttributes that would print all HTML attributes unless a custom propFilter is provided.

```typescript
const MyComponent: React.FC<React.HTMLAttributes<HTMLDivElement>> = ()...
```

--------------------------------

### Styled components componentNameResolver

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Styled components example for componentNameResolver. Uses the getDefaultExportForFile helper exported by the parser to resolve the component name for styled components.

```typescript
componentNameResolver: (exp, source) =>
  exp.getName() === "StyledComponentClass" && getDefaultExportForFile(source);
```

--------------------------------

### Example - inside a componentNameResolver

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser.md

Demonstrates using getDefaultExportForFile within a componentNameResolver option. It returns the default export name when the expression name is 'StyledComponentClass'.

```TypeScript
import { getDefaultExportForFile } from 'react-docgen-typescript';

const options = {
  componentNameResolver: (exp, source) =>
    exp.getName() === 'StyledComponentClass' && getDefaultExportForFile(source),
};
```

--------------------------------

### extractPropsFromTypeIfStatefulComponent method

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Extracts the props symbol from a stateful component type. Includes an example of usage with a class declaration.

```ts
public extractPropsFromTypeIfStatefulComponent(
  type: ts.Type
): ts.Symbol | null
```

```ts
const classType = checker.getTypeAtLocation(classDecl);
const props = parser.extractPropsFromTypeIfStatefulComponent(classType);
// props: ts.Symbol for React.Component<P, S>['props']  (or null)
```

--------------------------------

### withCustomConfig

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Creates a parser using a custom TypeScript configuration file and custom docgen options. The returned parser can be used to parse component files.

```APIDOC
## withCustomConfig

### Description
Creates a parser using a custom TypeScript configuration file and custom docgen options. The returned parser can be used to parse component files.

### Method
withCustomConfig

### Endpoint
withCustomConfig(tsconfigPath, options?)

### Parameters
#### Path Parameters
- **tsconfigPath** (string) - Required - Path to the TypeScript configuration file.

#### Options
- **options** (object) - Optional - Custom docgen options. Example: `{ savePropValueAsString: true }`.

### Request Example
```ts
const docgen = require("react-docgen-typescript");
const tsConfigParser = docgen.withCustomConfig("./tsconfig.json", {
  savePropValueAsString: true,
});
```

### Response
Returns a parser object with a `parse` method.
```

--------------------------------

### Create custom parsers with withDefaultConfig, withCompilerOptions, withCustomConfig

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Create custom parsers using withDefaultConfig, withCompilerOptions, or withCustomConfig. These allow customizing TypeScript compiler options or loading a tsconfig file.

```ts
const docgen = require("react-docgen-typescript");

// Create a parser with the default typescript config and custom docgen options
const customParser = docgen.withDefaultConfig(options);

const docs = customParser.parse("./path/to/component");

// Create a parser with the custom typescript and custom docgen options
const customCompilerOptionsParser = docgen.withCompilerOptions(
  { esModuleInterop: true },
  options
);

// Create a parser with using your typescript config
const tsConfigParser = docgen.withCustomConfig("./tsconfig.json", {
  savePropValueAsString: true,
});
```

--------------------------------

### new Parser(program, opts)

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Constructs a new Parser instance that stores the TypeScript checker and configuration options, and initializes internal caches for component and property information.

```APIDOC
## Constructor

### Description
Creates a Parser instance for performing docgen analysis on a given TypeScript program. The constructor immediately fetches the type checker from the program, which is held for the lifetime of the instance, and sets up internal caches.

### Signature
```ts
constructor(program: ts.Program, opts: ParserOptions)
```

### Parameters
- **program** (`ts.Program`) - Required - An already-created TypeScript program. The type checker is retrieved immediately from this program.
- **opts** (`ParserOptions`) - Required - Behavior options, including boolean flags and a prop filter. Unset options default to `false`.

### Usage Notes
- The instance caches `propertiesOfPropsCache` for property lookups and `componentsInfoCache` for component documents.

### Example
```ts
const parser = new Parser(program, { shouldExtractValuesFromUnion: true });
```
```

--------------------------------

### parse(fileName)

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/helper-modules.md

Documentation for the `parse` function from the `propTypesParser` module, a backward-compatibility shim that delegates to the main parser.

```APIDOC
## `parse(fileName)`

### Description
Backward-compatibility shim that delegates to the `parse` method from the `parser` module. This method exists for backward compatibility only; use the `parse` method from the `parser` file instead.

### Method
Function

### Signature
```ts
parse(fileName: string): ComponentDoc[]
```

### Parameters
- **fileName** (`string`) - Required - Component source file to parse.

### Return Type
`ComponentDoc[]` - Delegates to `parser.parse(fileName)` with default options.

### Example
```ts
const { parse } = require('react-docgen-typescript/lib/propTypesParser');

const docs = parse('./src/components/Grid.tsx');
const propsOfFirstComponent = docs[0].props;
```
```

--------------------------------

### withDefaultConfig

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Creates a parser with the default TypeScript configuration and custom docgen options. The returned parser can be used to parse component files.

```APIDOC
## withDefaultConfig

### Description
Creates a parser with the default TypeScript configuration and custom docgen options. The returned parser can be used to parse component files.

### Method
withDefaultConfig

### Endpoint
withDefaultConfig(options?)

### Parameters
#### Options
- **options** (object) - Optional - Custom docgen options. Example: `{ savePropValueAsString: true }`.

### Request Example
```ts
const docgen = require("react-docgen-typescript");
const customParser = docgen.withDefaultConfig(options);
const docs = customParser.parse("./path/to/component");
```

### Response
Returns a parser object with a `parse` method.
```

--------------------------------

### parse

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Parses a file for docgen information. Accepts a file path and optional options object, returning documentation for the component.

```APIDOC
## parse

### Description
Parses a file for docgen information. Accepts a file path and optional options object, returning documentation for the component.

### Method
parse

### Endpoint
parse(filePath, options?)

### Parameters
#### Path Parameters
- **filePath** (string) - Required - The path to the component file to parse.

#### Options
- **options** (object) - Optional - Configuration options for parsing. Example: `{ savePropValueAsString: true }`.

### Request Example
```ts
const docgen = require("react-docgen-typescript");
const options = { savePropValueAsString: true };
docgen.parse("./path/to/component", options);
```

### Response
Returns documentation information for the component.
```

--------------------------------

### withCompilerOptions

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Creates a parser with custom TypeScript compiler options and custom docgen options. The returned parser can be used to parse component files.

```APIDOC
## withCompilerOptions

### Description
Creates a parser with custom TypeScript compiler options and custom docgen options. The returned parser can be used to parse component files.

### Method
withCompilerOptions

### Endpoint
withCompilerOptions(compilerOptions, options?)

### Parameters
#### Compiler Options
- **compilerOptions** (object) - Required - TypeScript compiler options. Example: `{ esModuleInterop: true }`.

#### Options
- **options** (object) - Optional - Custom docgen options. Example: `{ savePropValueAsString: true }`.

### Request Example
```ts
const docgen = require("react-docgen-typescript");
const customCompilerOptionsParser = docgen.withCompilerOptions(
  { esModuleInterop: true },
  options
);
```

### Response
Returns a parser object with a `parse` method.
```

--------------------------------

### FileParser.parseWithProgramProvider

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/types.md

Parses files, optionally using a caller-built ts.Program, and returns an array of ComponentDoc objects.

```APIDOC
## FileParser.parseWithProgramProvider

### Description
Parses files, optionally using a caller-built ts.Program, and returns an array of ComponentDoc objects.

### Method
parseWithProgramProvider

### Signature
`parseWithProgramProvider(filePathOrPaths: string | string[], programProvider?: () => ts.Program): ComponentDoc[]`

### Parameters
- **filePathOrPaths** (string | string[]) - Required - The file path or array of file paths to parse.
- **programProvider** (() => ts.Program) - Optional - A function that returns a TypeScript Program to use for parsing.

### Returns
- **ComponentDoc[]** - An array of parsed component documentation objects.

### Example
```ts
const parser = withDefaultConfig();
const programProvider = () => ts.createProgram(['./src'], {});
const docs = parser.parseWithProgramProvider('./src/Button.tsx', programProvider);
```
```

--------------------------------

### parse

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser.md

Parses one or more component source files and returns an array of ComponentDoc objects. It is a convenience wrapper over withCompilerOptions(defaultOptions, parserOpts).parse(filePathOrPaths).

```APIDOC
## parse

### Description
Parses one or more component source files and returns an array of ComponentDoc objects. It is a convenience wrapper over withCompilerOptions(defaultOptions, parserOpts).parse(filePathOrPaths).

### Signature
```ts
export function parse(
  filePathOrPaths: string | string[],
  parserOpts: ParserOptions = defaultParserOpts
)
```

### Parameters
- **filePathOrPaths** (string | string[]) - Required - Path(s) to the component source file/s to parse (.ts / .tsx / .d.ts). Relative paths are resolved against the current working directory by the created ts.Program.
- **parserOpts** (ParserOptions) - Optional - Behavior options; see configuration.md.

### Return Type
ComponentDoc[] - One ComponentDoc per resolved component; see types.md. Files that do not resolve to a source file in the program produce no entries.

### Example - basic call
```ts
const docgen = require('react-docgen-typescript');

const docs = docgen.parse('./src/components/Button.tsx', {
  savePropValueAsString: true,
});
// docs: ComponentDoc[]
// docs[0].displayName  -> 'Button'
// docs[0].props['disabled'].defaultValue -> 'false' (string, because savePropValueAsString)
```

### Example - multiple files + filtering
```ts
import { parse } from 'react-docgen-typescript';

const docs = parse(
  ['./src/components/Button.tsx', './src/components/Grid.tsx'],
  {
    propFilter: { skipPropsWithName: ['as', 'id'], skipPropsWithoutDoc: true },
    shouldExtractLiteralValuesFromEnum: true,
  }
);

for (const doc of docs) {
  console.log(doc.displayName, Object.keys(doc.props));
}
```
```

--------------------------------

### Parse multiple files with propFilter

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser.md

Parses multiple files with a propFilter that skips props named 'as' or 'id' and skips props without documentation, plus shouldExtractLiteralValuesFromEnum. Then logs each component's displayName and prop keys.

```ts
import { parse } from 'react-docgen-typescript';

const docs = parse(
  ['./src/components/Button.tsx', './src/components/Grid.tsx'],
  {
    propFilter: { skipPropsWithName: ['as', 'id'], skipPropsWithoutDoc: true },
    shouldExtractLiteralValuesFromEnum: true,
  }
);

for (const doc of docs) {
  console.log(doc.displayName, Object.keys(doc.props));
}
```

--------------------------------

### getComponentInfo(exp, source)

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Retrieves the component documentation for a given export symbol and source file. This method is a core part of the Parser class, returning a ComponentDoc object or null if the symbol does not represent an extractable component.

```APIDOC
## getComponentInfo

### Description
Extracts component documentation for a specific exported symbol from a source file. Called for each exported symbol to build its documentation.

### Method
`getComponentInfo(exp: ts.Symbol, source: ts.SourceFile)`

### Parameters
- `exp` (`ts.Symbol`) - Required - The exported symbol for which to extract documentation.
- `source` (`ts.SourceFile`) - Required - The source file containing the symbol.

### Returns
- `ComponentDoc | null` - The component documentation if successful, otherwise `null`.

### Example
```ts
const doc = parser.getComponentInfo(exp, source);
if (doc) console.log(doc.displayName, Object.keys(doc.props));
```
```

--------------------------------

### Import parser functions from react-docgen-typescript

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser.md

Shows the two import paths for the parser module: the recommended top-level import and the deep module import that also includes all types.

```ts
// top-level (recommended)
import { parse, withDefaultConfig, withCustomConfig, withCompilerOptions,
  getDefaultExportForFile } from 'react-docgen-typescript';

// or the deep module (same symbols plus all types)
import * as parser from 'react-docgen-typescript/lib/parser';
```

--------------------------------

### FileParser.parse

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/types.md

Parses one or more files using the bound compiler options and returns an array of ComponentDoc objects.

```APIDOC
## FileParser.parse

### Description
Parses one or more files using the bound compiler options and returns an array of ComponentDoc objects.

### Method
parse

### Signature
`parse(filePathOrPaths: string | string[]): ComponentDoc[]`

### Parameters
- **filePathOrPaths** (string | string[]) - Required - The file path or array of file paths to parse.

### Returns
- **ComponentDoc[]** - An array of parsed component documentation objects.

### Example
```ts
const parser = withDefaultConfig();
const docs = parser.parse('./src/Button.tsx');
```
```

--------------------------------

### Styleguidist integration with withDefaultConfig

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Configure React Styleguidist to use react-docgen-typescript as the propsParser with default TypeScript configuration.

```javascript
module.exports = {
  propsParser: require("react-docgen-typescript").withDefaultConfig([
    parserOptions,
  ]).parse,
};
```

--------------------------------

### getReturnDescription method

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Retrieves the text of a @returns JSDoc tag as display parts.

```ts
public getReturnDescription(
  symbol: ts.Symbol
): SymbolDisplayPart[] | undefined
```

--------------------------------

### Styleguidist integration with withCustomConfig

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/README.md

Configure React Styleguidist to use react-docgen-typescript with a custom tsconfig file.

```javascript
module.exports = {
  propsParser: require("react-docgen-typescript").withCustomConfig(
    "./tsconfig.json",
    [parserOptions]
  ).parse,
};
```

--------------------------------

### getMethodsInfo method

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Returns detailed information for public methods tagged with @public.

```ts
public getMethodsInfo(type: ts.Type): Method[]
```

--------------------------------

### FileParser interface with parse and parseWithProgramProvider methods

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/types.md

Defines the FileParser interface returned by withDefaultConfig, withCustomConfig, and withCompilerOptions. The parse method parses one or more files using bound compiler options, while parseWithProgramProvider optionally accepts a caller-built ts.Program.

```TypeScript
export interface FileParser {
  parse(filePathOrPaths: string | string[]): ComponentDoc[];
  parseWithProgramProvider(
    filePathOrPaths: string | string[],
    programProvider?: () => ts.Program
  ): ComponentDoc[];
}
```

--------------------------------

### buildFilter

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/helper-modules.md

The buildFilter function constructs a PropFilter based on the provided ParserOptions. It returns a filter function that determines whether a prop should be included in the documentation. The filter logic handles skipping children props without documentation, applying a custom propFilter function, and applying static filter options like skipPropsWithName and skipPropsWithoutDoc.

```APIDOC
import {
  Component,
  ParserOptions,
  PropFilter,
  PropItem,
  StaticPropFilter
} from './parser';

export function buildFilter(opts: ParserOptions): PropFilter {
  return (prop: PropItem, component: Component) => {
    const { propFilter } = opts;
    // skip children property in case it has no custom documentation
    if (
      prop.name === 'children' &&
      prop.description.length === 0 &&
      opts.skipChildrenPropWithoutDoc !== false
    ) {
      return false;
    }
    if (typeof propFilter === 'function') {
      const keep = propFilter(prop, component);
      if (!keep) {
        return false;
      }
    } else if (propFilter) {
      const { skipPropsWithName, skipPropsWithoutDoc } = propFilter as StaticPropFilter;
      if (
        skipPropsWithName &&
        skipPropsWithName.includes(prop.name)
      ) {
        return false;
      }
      if (
        skipPropsWithoutDoc &&
        prop.description.length === 0
      ) {
        return false;
      }
    }
    return true;
  };
}
```

--------------------------------

### Render Column with prop2, prop3, prop4

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/examples/react-styleguidist-example/components/Column.md

Use this JSX snippet to render a Column component with specified props. The prop2 is set to 0, prop3 is null, and prop4 is set to the string "option1".

```jsx
<Column prop2={0} prop3={null} prop4="option1" />
```

--------------------------------

### Filter missing files in parseWithProgramProvider

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/errors.md

This snippet demonstrates how the parser filters out file paths that do not exist or are not included in the program, resulting in no error and an empty result for non-existent inputs.

```ts
return filePaths
  .map(filePath => program.getSourceFile(filePath))
  .filter(
    (sourceFile): sourceFile is ts.SourceFile =>
      typeof sourceFile !== 'undefined'
  )
```

--------------------------------

### ComponentDoc

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/types.md

The ComponentDoc interface represents the parsed documentation for a single component. It is produced by the parser and returned by the parse functions.

```APIDOC
## ComponentDoc

### Description
The `ComponentDoc` interface represents the parsed documentation for a single component. It is produced by `Parser.getComponentInfo` and returned by the `parse` functions.

### Fields
- **expression** (`ts.Symbol`) - Optional - Present only when `shouldIncludeExpression` is set: the resolved component symbol (after `forwardRef`/`memo`/alias unwrapping).
- **rootExpression** (`ts.Symbol`) - Optional - Present only when `shouldIncludeExpression` is set: the original symbol as passed in.
- **displayName** (`string`) - Required - Resolved component name (resolver → `@visibleName` tag → computed name / default-export name). Sub-components are prefixed, e.g. `Object.Component`.
- **filePath** (`string`) - Required - The source file path of the component (from `source.fileName`).
- **description** (`string`) - Required - Main JSDoc description of the component.
- **props** (`Props`) - Required - Parsed props keyed by prop name. Empty (`{}`) for components found without a resolvable props type.
- **methods** (`Method[]`) - Required - Public (`@public`-tagged) methods of the component type.
- **tags** (`StringIndexedObject<string>`) - Optional - JSDoc tags map, e.g. `{ visibleName: 'Foo', default: '…' }`.

### Example Shape
```json
{
  "displayName": "Column",
  "filePath": "/repo/src/Column.tsx",
  "description": "Form column.",
  "tags": {},
  "props": {
    "prop1": { "name": "prop1", "required": false, "type": { "name": "string" }, "description": "prop1 description", "defaultValue": null }
  },
  "methods": []
}
```
```

--------------------------------

### trimFileName(fileName, cwd?, platform?)

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/helper-modules.md

Relativizes a file path against a reference directory, keeping exactly one parent directory segment. It walks up from the current working directory to find a common ancestor, preserving the original slash style and memoizing results.

```APIDOC
## Function: trimFileName

### Description
Relativizes a file path against a reference directory, keeping exactly one parent directory segment. It walks up from the current working directory to find a common ancestor, preserving the original slash style and memoizing results.

### Signature
```ts
import * as path from 'path';

const slashRegex = /[\\/]/g;
const fileNameCache = new Map<string, string>();
export function trimFileName(
  fileName: string,
  cwd: string = process.cwd(),
  platform?: 'posix' | 'win32'
): string;
```

### Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `fileName` | `string` | yes | — | Absolute (or relative) file path, typically a `ts.SourceFile.fileName`. |
| `cwd` | `string` | no | `process.cwd()` | Reference directory to which paths are relativized. |
| `platform` | `'posix' \| 'win32'` | no | host platform (`path`) | Forces path-library semantics; mainly for portability of tests. |

### Return Type
`string`

Returns the file name relative to `cwd`, keeping exactly one parent-directory segment: `path.relative(path.dirname(parent), normalizedFileName)` — e.g. `/repo/packages/a/src/Props.ts` with `cwd=/repo/packages/a` yields `src/Props.ts`. The algorithm walks `cwd` upward until `normalizedFileName` starts with a candidate parent (monorepo friendly); if no common ancestor is found, the original `fileName` is returned unchanged. Original slash style (`/` vs `\`) is preserved, and results are memoized in a module-level `fileNameCache` keyed by the raw input.

### Example
```ts
import { trimFileName } from 'react-docgen-typescript/lib/trimFileName';

trimFileName('/repo/apps/web/src/Button.tsx'); // 'src/Button.tsx' (cwd = /repo/apps/web)
trimFileName('C:\\repo\\src\\Props.ts', undefined, 'win32'); // 'src\\Props.ts'
```
```

--------------------------------

### Throwing error for unreadable tsconfig

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/errors.md

This code snippet demonstrates how the library throws an error when the provided tsconfig.json path is invalid or unreadable.

```ts
const errorText = `Cannot load custom tsconfig.json from provided path: ${tsconfigPath}, with error code: ${error.code}, message: ${error.messageText}`;
throw new Error(errorText);
```

--------------------------------

### Styleguidist + filtering + Storybook-friendly enums

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/configuration.md

Configure the parser for Styleguidist with filtering and Storybook-friendly enum handling. Skips props named 'as' or 'id' and props without doc comments, extracts literal enum values, removes undefined from optional props, sorts unions, saves prop values as strings, and documents children even without comments.

```ts
const { withDefaultConfig } = require('react-docgen-typescript');

const parser = withDefaultConfig({
  propFilter: { skipPropsWithName: ['as', 'id'], skipPropsWithoutDoc: true },
  shouldExtractLiteralValuesFromEnum: true,
  shouldRemoveUndefinedFromOptional: true,
  shouldSortUnions: true,
  savePropValueAsString: true,
  skipChildrenPropWithoutDoc: false, // document children even without comments
});

module.exports = {
  propsParser: parser.parse,
};
```

--------------------------------

### ParserOptions and StaticPropFilter interfaces

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/configuration.md

Defines the ParserOptions interface and the StaticPropFilter sub-interface. Use these types when configuring the parser via parse, withDefaultConfig, withCustomConfig, withCompilerOptions, or the Parser constructor. The propFilter can be a function or a StaticPropFilter object; componentNameResolver overrides displayName; several boolean flags control enum extraction, union sorting, and optional-prop handling.

```ts
export interface ParserOptions {
  propFilter?: StaticPropFilter | PropFilter;
  componentNameResolver?: ComponentNameResolver;
  shouldExtractLiteralValuesFromEnum?: boolean;
  shouldRemoveUndefinedFromOptional?: boolean;
  shouldExtractValuesFromUnion?: boolean;
  shouldSortUnions?: boolean;
  skipChildrenPropWithoutDoc?: boolean;
  savePropValueAsString?: boolean;
  shouldIncludePropTagMap?: boolean;
  shouldIncludeExpression?: boolean;
  customComponentTypes?: string[];
}

export interface StaticPropFilter {
  skipPropsWithName?: string[] | string;
  skipPropsWithoutDoc?: boolean;
}
```

--------------------------------

### Basic parse call with savePropValueAsString

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser.md

Basic call to parse a single file with savePropValueAsString: true. The comment shows the expected output: docs is an array of ComponentDoc, displayName is 'Button', and defaultValue is a string because of the option.

```ts
const docgen = require('react-docgen-typescript');

const docs = docgen.parse('./src/components/Button.tsx', {
  savePropValueAsString: true,
});
// docs: ComponentDoc[]
// docs[0].displayName  -> 'Button'
// docs[0].props['disabled'].defaultValue -> 'false' (string, because savePropValueAsString)
```

--------------------------------

### getPropsInfo method signature

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

The signature for the getPropsInfo method as declared in src/parser.ts.

```ts
public getPropsInfo(
  propsObj: ts.Symbol,
  defaultProps: StringIndexedObject<string> = {}
): Props
```

--------------------------------

### getPropMap method signature

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Maps property or binding names to literal values, skipping spread assignments and unnamed properties.

```ts
public getPropMap(
  properties: ts.NodeArray<ts.PropertyAssignment | ts.BindingElement>
): StringIndexedObject<string | boolean | number | null>
```

--------------------------------

### getComponentInfo(exp, source, componentNameResolver?, customComponentTypes?)

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Analyzes a TypeScript export symbol and returns a ComponentDoc object containing component metadata such as displayName, props, methods, and tags. Returns null for non-component symbols.

```APIDOC
## getComponentInfo(exp, source, componentNameResolver?, customComponentTypes?)

### Description
Analyzes a TypeScript export symbol and returns a ComponentDoc object containing component metadata such as displayName, props, methods, and tags. Returns null for non-component symbols.

### Method
Method call (TypeScript)

### Signature
```ts
public getComponentInfo(
  exp: ts.Symbol,
  source: ts.SourceFile,
  componentNameResolver: ComponentNameResolver = () => undefined,
  customComponentTypes: ParserOptions['customComponentTypes'] = []
): ComponentDoc | null
```

### Parameters
- **exp** (ts.Symbol) - Required - Export symbol to analyze (e.g., from `checker.getExportsOfModule`).
- **source** (ts.SourceFile) - Required - The source file containing the export.
- **componentNameResolver** (ComponentNameResolver) - Optional - Default: `() => undefined` - If it returns a string, that string is used as `displayName`; otherwise naming falls back to the `@visibleName` JSDoc tag, then `computeComponentName`.
- **customComponentTypes** (string[]) - Optional - Default: `[]` - Extra React-component type names to recognize, e.g. `['OverridableComponent']`, appended to the built-in list.

### Return Type
`ComponentDoc | null`. `null` is returned (and cached) for non-component symbols: `Requireable`/`Validator` (`prop-types` exports), symbols with empty declarations, or stateless symbols that cannot be resolved to a comment source.

### Behavior
- Unwraps property assignments to identifiers and `forwardRef(...)`/`memo(...)` call expressions (`MemoExoticComponent`, `ForwardRefExoticComponent`).
- Detects props via `extractPropsFromTypeIfStatelessComponent(type)` then `extractPropsFromTypeIfStatefulComponent(type)` (order matters: stateless check first).
- Extracts default prop values with `extractDefaultPropsFromComponent(commentSource, sourceFile)`.
- Builds props with `getPropsInfo(propsType, defaultProps)`, then applies `propFilter(prop, { name: displayName })` per prop; dropped props are deleted from the result.
- `displayName` resolution order: `componentNameResolver(...)` → `tags.visibleName` → `computeComponentName(...)` (which honors a `displayName` class/function property assignment, then the default-export name via `getDefaultExportForFile`).
- When `shouldIncludeExpression` is set, adds `expression` (resolved symbol) and `rootExpression` (original symbol) to the result.
- Components that are *not* resolvable to props but have both a description and a display name yield `{ …, props: {} }`.
- Results are cached; the cache is keyed by `` `${filePath}_${originalName}` ``.

### Example — basic call
```ts
const checker = program.getTypeChecker();
const source = program.getSourceFile('/abs/src/Button.tsx');
const moduleSymbol = checker.getSymbolAtLocation(source);

const docs = checker
  .getExportsOfModule(moduleSymbol)
  .map((exp) => parser.getComponentInfo(exp, source))
  .filter((d): d is NonNullable<typeof d> => d !== null);

// docs[0].displayName, docs[0].filePath, docs[0].description,
// docs[0].props, docs[0].methods, docs[0].tags
```

### Example — custom resolver & custom component types
```ts
const doc = parser.getComponentInfo(
  exp,
  source,
  (exp, source) => (exp.getName() === 'StyledComponentClass' ? 'Styled' : undefined),
  ['OverridableComponent'] // extra type names recognized as components
);
```
```

--------------------------------

### MethodParameter and MethodParameterType interfaces

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/types.md

Defines the structure for method parameters. MethodParameter includes name, optional description, and a type wrapper. MethodParameterType holds the stringified type name. Produced by Parser.getParameterInfo and consumed by Method.params.

```TypeScript
export interface MethodParameter {
  name: string;
  description?: string | null;
  type: MethodParameterType;
}

export interface MethodParameterType {
  name: string;
}
```

--------------------------------

### getComponentInfo method signature

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

The public signature for the getComponentInfo method as defined in the parser class.

```ts
public getComponentInfo(
  exp: ts.Symbol,
  source: ts.SourceFile,
  componentNameResolver: ComponentNameResolver = () => undefined,
  customComponentTypes: ParserOptions['customComponentTypes'] = []
): ComponentDoc | null
```

--------------------------------

### extractDefaultPropsFromComponent method signature

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Scans a source file to extract default prop values from class static properties, component assignments, or destructured parameters.

```ts
public extractDefaultPropsFromComponent(
  symbol: ts.Symbol,
  source: ts.SourceFile
)
```

--------------------------------

### getPropsInfo(propsObj, defaultProps)

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Extracts prop metadata from a TypeScript symbol representing a component's props object. Returns a map of prop names to PropItem objects, including requiredness, type, description, and default value.

```APIDOC
## getPropsInfo(propsObj, defaultProps)

### Description
Extracts prop metadata from a TypeScript symbol representing a component's props object. Returns a map of prop names to PropItem objects, including requiredness, type, description, and default value.

### Method
public method

### Signature
public getPropsInfo(
  propsObj: ts.Symbol,
  defaultProps: StringIndexedObject<string> = {}
): Props

### Parameters
- **propsObj** (ts.Symbol) - Required - Symbol of the props object — the first function parameter (stateless) or the `props` instance property (stateful).
- **defaultProps** (StringIndexedObject<string>) - Optional - Map of prop name → serialized default value from code (usually from `extractDefaultPropsFromComponent`). Default: `{}`.

### Return Type
`Props` — `StringIndexedObject<PropItem>`, keyed by prop name.

### Behavior
- Gets apparent properties of the props type; for union/intersection types merges `(checker as any).getAllPossiblePropertiesOfTypes(...)` results with base props (props already present via `baseProps` override union members).
- Per prop: computes requiredness (`!isOptional(prop) && !hasCodeBasedDefault && all declarations lack a `?` token && baseProp is not optional`), the docgen type (a `@type` JSDoc tag overrides the inferred type), description, `parent`, `declarations`, and `defaultValue`.
- `defaultValue` is `{ value: <defaultProps[propName]> }` if the prop has a code default; else `{ value: <@default JSDoc tag> }` if present; else `null`.
- Props from `node_modules` parents are cached in `propertiesOfPropsCache` keyed by `` `${parent.fileName}_${propName}` ``.
- With `shouldIncludePropTagMap`, the JSDoc `tags` map is attached to each `PropItem` and the description uses only the main comment.
```

--------------------------------

### getParameterInfo method

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Extracts parameter information from a call signature, including names and doc comments.

```ts
public getParameterInfo(callSignature: ts.Signature): MethodParameter[]
```

--------------------------------

### getDocgenType method signature

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

The method signature as declared in the parser class.

```ts
public getDocgenType(propType: ts.Type, isRequired: boolean): PropItemType
```

--------------------------------

### Parser class signature with private fields and constructor declaration at src/parser.ts:219

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Shows the Parser class declaration, including private readonly fields for configuration options and two caches (propertiesOfPropsCache and componentsInfoCache), followed by the constructor signature expecting a ts.Program and ParserOptions. The constructor immediately fetches the type checker via program.getTypeChecker(). Use this as a reference for understanding Parser internals when constructing it directly.

```typescript
export class Parser {
  private readonly checker: ts.TypeChecker;
  private readonly propFilter: PropFilter;
  private readonly shouldRemoveUndefinedFromOptional: boolean;
  private readonly shouldExtractLiteralValuesFromEnum: boolean;
  private readonly shouldExtractValuesFromUnion: boolean;
  private readonly shouldSortUnions: boolean;
  private readonly savePropValueAsString: boolean;
  private readonly shouldIncludePropTagMap: boolean;
  private readonly shouldIncludeExpression: boolean;
  private propertiesOfPropsCache: Map<string, PropItem> = new Map();
  private componentsInfoCache: Map<string, ComponentDoc | null> = new Map();

  constructor(program: ts.Program, opts: ParserOptions) {
```

--------------------------------

### trimFileName function source code

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/helper-modules.md

The complete implementation of trimFileName, which normalizes paths, walks up from cwd to find a common ancestor, and returns a relative path with one parent segment. It preserves original slash style and caches results in a module-level Map.

```typescript
import * as path from 'path';

const slashRegex = /[\\/]/g;
const fileNameCache = new Map<string, string>();
export function trimFileName(
  fileName: string,
  cwd: string = process.cwd(),
  platform?: 'posix' | 'win32'
): string {
  if (fileNameCache.has(fileName)) return fileNameCache.get(fileName) as string;
  // This allows tests to run regardless of current platform
  const pathLib = platform ? path[platform] : path;

  // Typescript formats Windows paths with forward slashes. For easier use of
  // the path utilities, normalize to platform-standard slashes, then restore
  // the original slashes when returning the result.
  const originalSep = fileName.match(slashRegex)?.[0] || pathLib.sep;
  const normalizedFileName = pathLib.normalize(fileName);
  const root = pathLib.parse(cwd).root;

  // Walk up paths from the current directory until we find a common ancestor,
  // and return the path relative to that. This will work in either a single-
  // package repo or a monorepo (where dependencies may be installed at the
  // root, but commands may be run in a package folder).
  let parent = cwd;
  do {
    if (normalizedFileName.startsWith(parent)) {
      const finalPathName = pathLib
        // Preserve the parent directory name to match existing behavior
        .relative(pathLib.dirname(parent), normalizedFileName)
        // Restore original type of slashes
        .replace(slashRegex, originalSep);
      fileNameCache.set(fileName, finalPathName);
      return finalPathName;
    }
    parent = pathLib.dirname(parent);
  } while (parent !== root);

  fileNameCache.set(fileName, fileName);
  // No common ancestor, so return the path as-is
  return fileName;
}
```

--------------------------------

### getFullJsDocComment method signature

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser-class.md

Rebuilds the full JSDoc comment by normalizing text and reformatting tags.

```ts
public getFullJsDocComment(symbol: ts.Symbol): JSDoc
```

--------------------------------

### parse function body

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/api-reference/parser.md

The body of the parse function, showing it as a convenience wrapper over withCompilerOptions with defaultOptions and the provided parserOpts.

```ts
withCompilerOptions(defaultOptions, parserOpts).parse(filePathOrPaths)
```

--------------------------------

### Default ParserOptions export

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/configuration.md

Exports the default ParserOptions value as an empty object. Use this as a base when you need to provide a full ParserOptions object without specifying every option. The comment indicates the source location in src/parser.ts.

```ts
export const defaultParserOpts: ParserOptions = {};   // src/parser.ts:103
```

--------------------------------

### Minimal parse with react-docgen-typescript

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/configuration.md

Use the default parser to extract prop types from a single TypeScript component file. All default options are applied: full comment descriptions, required flags, and literal types.

```ts
const docs = require('react-docgen-typescript').parse('./Button.tsx');
// all defaults: full comment descriptions, required flags, literal types
```

--------------------------------

### Custom component types + expression symbols

Source: https://github.com/styleguidist/react-docgen-typescript/blob/master/_autodocs/configuration.md

Use custom compiler options and include expression symbols and prop tag maps. Set customComponentTypes to include 'OverridableComponent', enable shouldIncludeExpression and shouldIncludePropTagMap. The parsed doc exposes expression/rootExpression as ts.Symbol and prop tags like default and type.

```ts
import { withCompilerOptions } from 'react-docgen-typescript';

const parser = withCompilerOptions(
  { esModuleInterop: true, strict: true, jsx: 'react' },
  {
    customComponentTypes: ['OverridableComponent'],
    shouldIncludeExpression: true,
    shouldIncludePropTagMap: true,
  }
);

const [doc] = parser.parse('./src/Overridable.tsx');
// doc.expression / doc.rootExpression: ts.Symbol
// doc.props.button.tags: { default: '…', type: '…' }
```
Tokens:
Raw