Babel Plugin for React Docgen

Common errors

• TypeError: Cannot read properties of undefined (reading '__docgenInfo')

  cause The plugin was not applied to the component's file, or Babel did not process the file with the plugin.
  fix Verify that `babel-plugin-react-docgen` is correctly listed in your `babel.config.js` or `.babelrc` and that the file containing the component is being transpiled by Babel.

• ReferenceError: MY_GLOBAL_DOCS is not defined

  cause The `DOC_GEN_COLLECTION_NAME` option was used, but the specified global variable (`MY_GLOBAL_DOCS`) was not initialized before the transformed code ran.
  fix Before any components processed by the plugin are executed, ensure the global variable is initialized as an empty object (e.g., `window.MY_GLOBAL_DOCS = {};` in browsers or `global.MY_GLOBAL_DOCS = {};` in Node.js).

• Error: Could not resolve file path for resolver 'myCustomResolver'

  cause A custom resolver was specified by name in the plugin options, but Babel or `react-docgen` could not locate or load the resolver module.
  fix Ensure the path to your custom resolver is correct and that it can be resolved by Node.js's module resolution system. Alternatively, provide the resolver function directly rather than its string name.

Warnings

• breaking Version 3.0.0 introduced breaking changes by upgrading to Babel 7 and `react-docgen` v5. This requires updating Babel-related dependencies to their v7+ counterparts and reviewing Babel configuration syntax.
  Fix: Upgrade `@babel/core`, `@babel/cli`, and other Babel presets/plugins to their Babel 7 compatible versions. Adjust `.babelrc` or `babel.config.js` syntax as per Babel 7 migration guides.
• breaking Version 4.0.0 bumped `react-docgen` to v6.0.0, which included significant changes to resolvers and handlers. Custom resolvers or handlers might require updates.
  Fix: Consult the `react-docgen` v6 changelog for specific API changes related to resolvers and handlers. Update any custom implementations to conform to the new `react-docgen` API.
• gotcha When using the `DOC_GEN_COLLECTION_NAME` option to collect all docgen information into a global variable, that global variable must be initialized (e.g., `window.MY_DOCS = {}` or `global.MY_DOCS = {}`) before any code processed by this plugin executes.
  Fix: Ensure the specified global variable is an initialized object in your application's entry point or setup script before any React components are loaded.
• gotcha The underlying `react-docgen` library expects `propTypes` to be imported from the `prop-types` package, not `React.PropTypes`. Using `React.PropTypes` (deprecated since React v15.5) may lead to incorrect or incomplete docgen information.
  Fix: Refactor components to import `PropTypes` from the `prop-types` package and use it (e.g., `import PropTypes from 'prop-types'; MyComponent.propTypes = { ... };`).

Install

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

Imports

• default
  wrong:

  const babelPluginReactDocgen = require('babel-plugin-react-docgen');

  correct:

  import babelPluginReactDocgen from 'babel-plugin-react-docgen';

  While it's possible to import the plugin function directly into `babel.config.js` (an ESM context) for programmatic use, the more common and recommended pattern is to reference the plugin by its string name in the `plugins` array. The package is ESM compatible for direct import in appropriate environments.
• PluginReferenceString
  wrong:

  plugins: ['babel-plugin-react-docgen']

  correct:

  plugins: ['react-docgen']

  The most common way to use the plugin is by its short string name 'react-docgen' within the 'plugins' array of your Babel configuration (e.g., .babelrc or babel.config.js). The full package name also works but is less common.
• PluginWithOptions
  wrong:

  plugins: ['react-docgen', { resolver: 'findAllExportedComponentDefinition' }]

  correct:

  plugins: [['react-docgen', { resolver: 'findAllExportedComponentDefinition' }]]

  When passing options to the plugin, its entry in the Babel 'plugins' array must be an array itself. The first element is the plugin name (string), and the second is the options object.

Quickstart

Demonstrates the basic installation and configuration of the plugin in `babel.config.js`, along with an example React component showing how `__docgenInfo` is generated.

npm install -D babel-plugin-react-docgen @babel/core @babel/cli

// babel.config.js
module.exports = {
  plugins: [
    "react-docgen"
  ],
  // Ensure Babel processes your React files, e.g., with @babel/preset-react
  // presets: ['@babel/preset-react', '@babel/preset-env']
};

// src/Button.jsx
import React from 'react';
import PropTypes from 'prop-types'; // Use prop-types package

/**
 * This is an example button component for demonstration purposes.
 */
export default class Button extends React.Component {
  render() {
    const { label, onClick } = this.props;
    return (
      <button onClick={onClick}>{ label }</button>
    );
  }
}

Button.propTypes = {
  /**
   * The text label for the button.
   */
  label: PropTypes.string,
  /**
   * Function called when the button is clicked.
   */
  onClick: PropTypes.func,
};

// To access the generated info after Babel compilation (e.g., in a documentation builder)
// console.log(Button.__docgenInfo);
/* Expected structure of Button.__docgenInfo:
{
  description: 'This is an example button component for demonstration purposes.',
  props: {
    label: {
      type: { name: 'string' },
      required: false,
      description: 'The text label for the button.'
    },
    onClick: {
      type: { name: 'func' },
      required: false,
      description: 'Function called when the button is clicked.'
    }
  }
}
*/