React Docgen

Common errors

• Error: Cannot find module 'react-docgen'

  cause The `react-docgen` package is either not installed, or you are trying to import it using CommonJS `require()` in an ESM context (or vice-versa) without proper configuration or tooling.
  fix Ensure `react-docgen` is installed (`npm install react-docgen` or `yarn add react-docgen`). For ESM projects, use `import { parse } from 'react-docgen';`. If using CommonJS, check your `tsconfig.json` or bundler settings for module resolution.

• SyntaxError: Unknown type: VoidPattern

  cause This error occurs when `react-docgen` encounters a newer JavaScript syntax feature (like a `VoidPattern`) that it doesn't recognize. This was a known issue fixed in `react-docgen@8.0.1`.
  fix Update `react-docgen` to version 8.0.1 or newer (`npm update react-docgen` or `yarn upgrade react-docgen`).

• Error: No component definition found for ...

  cause The parser could not identify any React component definition within the provided source code using the default resolvers. This can happen with unusual export patterns, higher-order components (HOCs) not explicitly handled, or incorrect file paths/content.
  fix Verify that your component is defined and exported in a way `react-docgen` can understand (e.g., `export default function MyComponent`, `export const MyComponent = () => {}`). Consider using `parseWithCustomResolvers` and providing a custom resolver function if your component definition pattern is non-standard.

Warnings

• breaking Version 8.0.0 of `react-docgen` dropped support for Node.js 16, 17, 18, 19, and 21. Users must upgrade to Node.js 20.9.0 or newer 20.x versions, or Node.js 22.0.0 or any newer version.
  Fix: Upgrade your Node.js environment to a compatible version (e.g., Node.js 20.9.0+ or 22.0.0+).
• gotcha Parsing complex or highly dynamic React component patterns (e.g., HOCs, render props within highly nested structures, or non-standard component definitions) might not yield complete or accurate results with default resolvers and handlers. Custom resolvers and handlers may be required.
  Fix: For advanced use cases, refer to the `react-docgen` documentation on GitHub for examples of creating and using `customResolvers` and `customHandlers` with `parseWithCustomResolvers`.
• gotcha As of the provided package metadata, the official `README.md` for `react-docgen` was not available. Users might need to consult the GitHub repository directly for comprehensive usage examples, advanced configuration, and a full understanding of the API.
  Fix: Always refer to the official GitHub repository (github.com/reactjs/react-docgen) for the most up-to-date documentation and examples, especially when encountering unexpected parsing behaviors.
• gotcha `react-docgen` primarily works with static analysis of component code. It does not execute components or rely on runtime introspection, meaning runtime-only prop definitions or dynamically generated props will not be detected.
  Fix: Ensure that all props intended for documentation are statically defined in the component's source code, typically through TypeScript interfaces, JSDoc, or PropTypes.

Install

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

Imports

• parse
  wrong:

  const { parse } = require('react-docgen');

  correct:

  import { parse } from 'react-docgen';

  ESM is the preferred module system. While CommonJS `require` might work with transpilers, direct ESM imports are recommended for modern Node.js environments.
• parseWithCustomResolvers
  wrong:

  import parseWithCustomResolvers from 'react-docgen/lib/parseWithCustomResolvers';

  correct:

  import { parseWithCustomResolvers } from 'react-docgen';

  Use named imports from the main package entry point. Direct imports from `lib/` paths are not stable API.
• handlers
  wrong:

  const handlers = require('react-docgen').handlers;

  correct:

  import { handlers } from 'react-docgen';

  The `handlers` object contains various default handlers for parsing component features like `propTypeHandler`, `defaultPropsHandler`, etc.
• resolver.findAllExportedComponentDefinitions
  wrong:

  import { findAllExportedComponentDefinitions } from 'react-docgen/dist/resolver';

  correct:

  import { resolver } from 'react-docgen';
  const componentResolver = resolver.findAllExportedComponentDefinitions;

  Resolvers are exposed via the `resolver` object. Access specific resolvers as properties of this object, not via direct deep imports.
• DocgenResult
  wrong:

  import { DocgenResult } from 'react-docgen';

  correct:

  import type { DocgenResult } from 'react-docgen';

  TypeScript types should be imported using `import type` to ensure they are stripped from the JavaScript output.

Quickstart

This quickstart demonstrates how to use `react-docgen` to parse a TypeScript React functional component, extracting its display name, description, and detailed prop information including types, descriptions, and default values.

import { parse, resolver, handlers } from 'react-docgen';
import path from 'path';

const componentSource = `
/**
 * A button component for user interaction.
 */
interface ButtonProps {
  /**
   * The text content of the button.
   */
  label: string;
  /**
   * Callback fired when the button is clicked.
   */
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
  /**
   * Whether the button is disabled.
   * @default false
   */
  disabled?: boolean;
}

function Button({ label, onClick, disabled = false }: ButtonProps) {
  return (
    <button onClick={onClick} disabled={disabled}>
      {label}
    </button>
  );
}

export default Button;
`;

try {
  const results = parse(
    componentSource,
    resolver.findAllExportedComponentDefinitions,
    Object.values(handlers),
    { filename: 'Button.tsx' }
  );

  if (results.length > 0) {
    const doc = results[0];
    console.log(`Component Name: ${doc.displayName}`);
    console.log(`Description: ${doc.description}`);
    console.log('Props:');
    for (const propName in doc.props) {
      const prop = doc.props[propName];
      console.log(`  - ${propName}: ${prop.description} (Type: ${prop.type?.name}, Required: ${prop.required}, Default: ${prop.defaultValue?.value})`);
    }
  } else {
    console.log('No component definition found.');
  }
} catch (error) {
  console.error('Error parsing component:', error);
}