react-docgen-typescript

What is react-docgen-typescript?

The react-docgen-typescript package is a tool for extracting documentation from TypeScript React components. It parses TypeScript files and generates JSON output that describes the components, their props, methods, and other relevant information. This is particularly useful for creating documentation websites or integrating with other tools that require component metadata.

What are react-docgen-typescript's main functionalities?

Extracting Prop Types

This feature allows you to extract prop types from a TypeScript React component. The `parse` function reads the component file and returns a JSON object containing detailed information about the component's props.

const docgen = require('react-docgen-typescript');
const options = { savePropValueAsString: true };
const componentInfo = docgen.parse('path/to/your/component.tsx', options);
console.log(JSON.stringify(componentInfo, null, 2));

Customizing Parser Options

This feature allows you to customize the parser options to fit your needs. For example, you can choose to extract literal values from enums or remove `undefined` from optional props.

const docgen = require('react-docgen-typescript');
const options = { shouldExtractLiteralValuesFromEnum: true, shouldRemoveUndefinedFromOptional: true };
const componentInfo = docgen.parse('path/to/your/component.tsx', options);
console.log(JSON.stringify(componentInfo, null, 2));

Generating Documentation for Multiple Files

This feature allows you to generate documentation for multiple files at once. You can pass an array of file paths to the `parse` function, and it will return a combined JSON object with information about all the components.

const docgen = require('react-docgen-typescript');
const options = { savePropValueAsString: true };
const files = ['path/to/your/component1.tsx', 'path/to/your/component2.tsx'];
const componentInfo = docgen.parse(files, options);
console.log(JSON.stringify(componentInfo, null, 2));

Other packages similar to react-docgen-typescript

react-docgen

react-docgen is a similar tool that extracts documentation from React components, but it is designed for JavaScript rather than TypeScript. It parses the component files and generates JSON output describing the components. While it is powerful, it lacks the TypeScript-specific features of react-docgen-typescript.

typedoc

typedoc is a documentation generator for TypeScript projects. It can generate HTML or JSON documentation for TypeScript code, including React components. While it is more general-purpose compared to react-docgen-typescript, it can be used to document a wider range of TypeScript code, not just React components.

ts-morph

ts-morph is a TypeScript compiler API wrapper that allows for easy manipulation and analysis of TypeScript code. While it is not specifically designed for generating documentation, it can be used to extract information from TypeScript code, including React components, and generate custom documentation.

README

react-docgen-typescript

A simple parser for React properties defined in TypeScript instead of propTypes.

It can be used with React Styleguidist.

Installation

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

React Styleguidist integration

Include following line in your styleguide.config.js:

propsParser: require('react-docgen-typescript').withDefaultConfig([parserOptions]).parse

or if you want to use custom tsconfig file

propsParser: require('react-docgen-typescript').withCustomConfig('./tsconfig.json', [parserOptions]).parse

parserOptions

• propFilter:

  {
    skipPropsWithName?: string[] | string;
    skipPropsWithoutDoc?: boolean;
  }
  

  or

  (props: PropItem, component: Component) => boolean
  

  Note: children without a doc comment will not be documented.

• componentNameResolver:

  (exp: ts.Symbol, source: ts.SourceFile) => string | undefined | null | false
  

  If a string is returned, then the component will use that name. Else it will fallback to the default logic of parser.

Styled components example:

componentNameResolver: (exp, source) => exp.getName() === 'StyledComponentClass' && getDefaultExportForFile(source);

The parser exports getDefaultExportForFile helper through its public API.

Example

In the example folder you can see React Styleguidist integration.

The component Column.tsx

import * as React from 'react';
import { Component } from 'react';

/**
 * Column properties.
 */
export interface IColumnProps {
    /** prop1 description */
    prop1?: string;
    /** prop2 description */
    prop2: number;
    /**
     * prop3 description
     */
    prop3: () => void;
    /** prop4 description */
    prop4: 'option1' | 'option2' | 'option3';
}

/**
 * Form column.
 */
export class Column extends Component<IColumnProps, {}> {
    render() {
        return <div>Test</div>;
    }
}

Will generate the following stylesheet:

The functional component Grid.tsx

import * as React from 'react';

/**
 * Grid properties.
 */
export interface IGridProps {
    /** prop1 description */
    prop1?: string;
    /** prop2 description */
    prop2: number;
    /**
     * prop3 description
     */
    prop3: () => void;
    /** Working grid description */
    prop4: 'option1' | 'option2' | 'option3';
}

/**
 * Form Grid.
 */
export const Grid = (props: IGridProps) => {
    const smaller = () => {return;};
    return <div>Grid</div>;
};

Will generate the following stylesheet:

Contributions

The typescript is pretty complex and there are many different way how to define components and their props so it's realy hard to support all diferent use cases. That means only one thing, contributions are highly welcome. Just keep in mind that each PR should also include tests for the part it's fixing.

Thanks to contributors

@argshook Arijus Šukys

@asilgag Alberto Silva

@basarat Basarat Ali Syed

@brettjurgens Brett Jurgens - adding support for default props

@chrisalbert Chris Albert

@diegolanda Diego - support for different kinds of components

@dotcs Fabian Mueller - introduced parserOptions for skipping undocumented properties

@eps1lon Sebastian Silbermann

@Havret Krzysztof Havret

@JakeSidSmith Jake

@JocD Jacques Dukes - complete support for functional components and much more

@jrwebdev James Ravenscroft

@kbukum Kamil BUKUM

@marionebl Mario Nebl

@milesj Miles Johnson

@rkostrzewski Rafał Kostrzewski

@RoystonS Royston Shufflebotham - complete parser rewrite that use typescript parser in much better way and overcome many issues of previous implementation

@yoiang Ian G

@sapegin Artem Sapegin - fix for compatibility with react-styleguidist v5

@skeate Jonathan Skeate

@strothj Jason Strothmann

Thanks to others

The integration with React Styleguidist wouldn't be possible without Vyacheslav Slinko pull request #118 at React Styleguidist.