Babel Plugin for React TypeScript Docgen

1.5.1 · active · verified Sun Apr 19

babel-plugin-react-docgen-typescript is a Babel plugin designed to extract component documentation (docgen data) from React components written in TypeScript. It works by integrating into the Babel compilation pipeline, identifying and parsing TypeScript React files to generate metadata about their props, types, and descriptions. This data is typically consumed by documentation tools like Storybook to automatically generate prop tables and API documentation. The plugin, currently at version 1.5.1, explicitly leverages the `react-docgen-typescript` library for its core parsing logic. While functional, the plugin's documentation notes it's 'a bit of a hack' and can be 'very inefficient' if not properly configured with `include` and `exclude` regular expressions to limit the scope of files it processes. It does not specify a fixed release cadence but generally follows updates in the `react-docgen-typescript` or Babel ecosystems. Its main differentiator is its direct integration into Babel builds, offering a streamlined approach to collecting docgen data without requiring separate parsing steps.

Common errors

```
Plugin 'babel-plugin-react-docgen-typescript' not found.
```
cause The package `babel-plugin-react-docgen-typescript` or its peer dependency `@babel/core` is not installed or not resolvable by Babel.

fix Ensure `npm install --save-dev babel-plugin-react-docgen-typescript @babel/core` has been run and that the plugin is correctly listed in your Babel configuration.
```
My build process is significantly slower after adding babel-plugin-react-docgen-typescript.
```
cause The plugin is processing too many files, potentially all `.tsx` files in your project, due to broad or missing `include`/`exclude` configurations.

fix Add specific `include` and `exclude` regular expressions in your `.babelrc` plugin options (e.g., `"include": "src/components/.*\\.tsx$", "exclude": "src/components/.*\\.stories\\.tsx$"`) to limit processing only to actual component files.
```
Docgen data (prop tables, component descriptions) is not appearing in Storybook or other documentation tools.
```
cause This can be caused by an incorrect `docgenCollectionName`, inaccurate `include`/`exclude` patterns, or the Babel plugin not being applied to the correct component files during the build.

fix Verify that `docgenCollectionName` matches what your documentation tool expects. Double-check `include` and `exclude` regex patterns to confirm they are correctly targeting your component files. Ensure your Babel configuration is applied to the directories containing your React components.

Warnings

gotcha The plugin can introduce significant performance overhead during the build process if `include` and `exclude` options are not properly configured.
Fix: Always define `include` and `exclude` regular expressions in your plugin options to process only relevant component files and avoid unnecessary parsing.
gotcha The plugin is described by its maintainers as 'a bit of a hack', which might imply a less robust or non-standard implementation, potentially leading to unexpected behavior or fragility with future Babel/TypeScript updates.
Fix: Be mindful of this architectural note and test thoroughly when updating related dependencies (Babel, TypeScript, React) or when complex component patterns are used. Consider its fitness for critical production build pipelines.
gotcha The plugin internally relies on `react-docgen-typescript` for its core parsing logic. Breaking changes or updates in `react-docgen-typescript` might indirectly affect this plugin's behavior or compatibility.
Fix: Monitor release notes for both `babel-plugin-react-docgen-typescript` and `react-docgen-typescript` to anticipate potential issues when updating dependencies. Thoroughly test after any dependency updates.

Install

npm install babel-plugin-react-docgen-typescript npm
yarn add babel-plugin-react-docgen-typescript yarn
pnpm add babel-plugin-react-docgen-typescript pnpm

Imports

babel-plugin-react-docgen-typescript
wrong:
```
import plugin from 'babel-plugin-react-docgen-typescript'
```
correct:
```
plugins: [["babel-plugin-react-docgen-typescript", { /* options */ }]]
```
This package is a Babel plugin, configured via its string name in the `plugins` array of your `.babelrc` or `babel.config.js` file. It is not typically imported directly into application JavaScript/TypeScript files.

Quickstart

This quickstart demonstrates how to install `babel-plugin-react-docgen-typescript` and configure it in your `.babelrc` to extract documentation from TypeScript React components, useful for tools like Storybook.

// 1. Install necessary packages:
// npm install --save-dev babel-plugin-react-docgen-typescript @babel/core typescript react @babel/preset-typescript @babel/preset-react

// 2. Configure your .babelrc (or babel.config.js):
// .babelrc
const babelConfig = {
  plugins: [
    [
      "babel-plugin-react-docgen-typescript",
      {
        // Name of the global object where docgen data will be collected.
        // Useful for integration with tools like Storybook.
        "docgenCollectionName": "STORYBOOK_REACT_CLASSES",
        // Regex to include files for parsing. Crucial for performance.
        "include": "src/components/.*\\.tsx$",
        // Regex to exclude files, e.g., stories or test files.
        "exclude": "src/components/.*\\.stories\\.tsx$"
      }
    ]
  ],
  // Add these presets if you're working with TypeScript and React
  "presets": ["@babel/preset-typescript", "@babel/preset-react"]
};

// 3. Example TypeScript React Component (e.g., src/components/Button.tsx):
/*
import React from 'react';

interface ButtonProps {
  /**
   * The text content for the button.
   */
  label: string;
  /**
   * Callback when the button is clicked.
   */
  onClick: () => void;
}

/**
 * A simple button component with JSDoc comments for docgen.
 */
export const Button: React.FC<ButtonProps> = ({ label, onClick }) => {
  return (
    <button onClick={onClick}>
      {label}
    </button>
  );
};
*/

// During the Babel compilation process, this plugin will extract
// documentation from 'Button.tsx' (if it matches 'include') and store it 
// in 'global.STORYBOOK_REACT_CLASSES'. This data can then be consumed by 
// documentation tools like Storybook to generate prop tables.

view raw JSON →