React Docgen TypeScript Webpack Plugin

1.0.8 · active · verified Sun Apr 19

react-docgen-typescript-plugin is a webpack plugin designed to automatically extract and inject TypeScript-based documentation (docgen information) for React components directly into the webpack build output. This is particularly useful for tools like Storybook that consume docgen information to generate component documentation. The current stable version is `1.0.8`. The package appears to follow a frequent bug-fix release cadence, with minor updates addressing specific issues or dependency bumps, as evidenced by the recent v1.0.x patches. Its key differentiator is its seamless integration into the webpack build process, providing a 'fire-and-forget' solution for generating React component props documentation from TypeScript types, contrasting with loaders that might require more explicit configuration per file. It supports both Webpack 4 and 5 and allows for fine-grained control over `tsconfig.json` paths, compiler options, and file inclusion/exclusion.

Common errors

```
TypeError: (0, _reactDocgenTypescriptPlugin.default) is not a constructor or TypeError: ReactDocgenTypescriptPlugin is not a constructor
```
cause Incorrect import of the plugin when using CommonJS `require` or when `esModuleInterop` is false.

fix If using `require`, ensure you access the `.default` export: `const ReactDocgenTypescriptPlugin = require('react-docgen-typescript-plugin').default;`. If using `import` in a mixed ESM/CJS environment, ensure your `tsconfig.json` or bundler settings correctly handle default imports.
```
Error: Cannot find module 'typescript' or Cannot find module 'webpack'
```
cause The peer dependencies `typescript` or `webpack` are not installed or are not accessible.

fix Install the required peer dependencies: `npm install --save-dev typescript webpack` or `yarn add -D typescript webpack`. Ensure their versions meet the plugin's requirements (e.g., `typescript: >= 4.x`, `webpack: >= 4`).
```
Webpack compilation failed: TS2304: Cannot find name 'ts' in compilerOptions
```
cause When providing `compilerOptions` directly, the `ts` object from the TypeScript compiler API needs to be imported or available in scope.

fix Make sure `import ts from 'typescript';` is present in your webpack configuration file if you're using `ts.JsxEmit.Preserve` or similar enum values directly in `compilerOptions`.
```
Docgen information missing or incorrect for components
```
cause The plugin might be excluding your component files, or `allowSyntheticDefaultImports`/`esModuleInterop` might be interfering.

fix Check the `include` and `exclude` options to ensure your component files are being processed. Set `DEBUG=docgen:*` environment variable to get detailed logs on which modules are included/excluded and which docs are generated. Also, consider disabling `allowSyntheticDefaultImports` and `esModuleInterop` in your `tsconfig.json`.

Warnings

breaking Version 1.0.0 introduced breaking changes by adding support for Webpack 5. Projects migrating from older versions of webpack might need to upgrade the plugin.
Fix: Ensure you are using `react-docgen-typescript-plugin` v1.0.0 or higher for Webpack 5 projects. For Webpack 4, use `react-docgen-typescript-plugin` < 1.0.0.
gotcha TypeScript compiler options `allowSyntheticDefaultImports` and `esModuleInterop` can significantly impact the plugin's performance, making it harder and slower to process documentation.
Fix: For faster build times, it is recommended to turn off `allowSyntheticDefaultImports` and `esModuleInterop` in your `tsconfig.json` when using this plugin, if your project allows.
gotcha The `ReactDocgenTypescriptPlugin` is a default export, which can lead to incorrect `require` or `import` syntax depending on your module system configuration.
Fix: When using CommonJS `require`, access the plugin via `.default`: `const ReactDocgenTypescriptPlugin = require('react-docgen-typescript-plugin').default;`. For ESM `import`, use `import ReactDocgenTypescriptPlugin from 'react-docgen-typescript-plugin';`.
gotcha The `docgenCollectionName` option defaults to `STORYBOOK_REACT_CLASSES`. If you're not using Storybook or need a different global object, ensure to configure this option or set it to `null` to disable collection.
Fix: Set `docgenCollectionName: null` in the plugin options if you don't need docgen information to be collected into a global variable, or provide a custom string for your desired collection name: `new ReactDocgenTypescriptPlugin({ docgenCollectionName: 'MY_CUSTOM_DOCS' })`.

Install

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

Imports

ReactDocgenTypescriptPlugin
wrong:
```
const ReactDocgenTypescriptPlugin = require('react-docgen-typescript-plugin');
```
correct:
```
import ReactDocgenTypescriptPlugin from 'react-docgen-typescript-plugin';
```
The default export from the package is the plugin class itself. While `require().default` works in CommonJS, the preferred way for modern Node.js and TypeScript projects is `import`.

ReactDocgenTypescriptPlugin with options

wrong:

new ReactDocgenTypescriptPlugin({ 'tsconfigPath': './tsconfig.dev.json' });

correct:

import ReactDocgenTypescriptPlugin from 'react-docgen-typescript-plugin';

new ReactDocgenTypescriptPlugin({ tsconfigPath: './tsconfig.dev.json' });

Options are passed as an object to the constructor. Property names should be camelCase as specified in the options table.

TypeScript compiler API
wrong:
```
const ts = require('typescript');
```
correct:
```
import ts from 'typescript';

new ReactDocgenTypescriptPlugin({ compilerOptions: { jsx: ts.JsxEmit.Preserve } });
```
The README uses `require('typescript')`, but for ESM-first projects or modern TypeScript, `import ts from 'typescript'` is more appropriate. Ensure `typescript` is installed.

Quickstart

This quickstart demonstrates how to integrate `react-docgen-typescript-plugin` into a basic webpack configuration for a TypeScript React project. It shows how to import the plugin and add it to the webpack `plugins` array, using its default settings which automatically pick up your root `tsconfig.json`.

import path from 'path';
import webpack from 'webpack';
import ReactDocgenTypescriptPlugin from 'react-docgen-typescript-plugin';
import ts from 'typescript';

const config: webpack.Configuration = {
  mode: 'development',
  entry: './src/index.tsx',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx'],
  },
  module: {
    rules: [
      {
        test: /\.(ts|tsx)$/,
        loader: 'ts-loader',
        exclude: /node_modules/,
      },
    ],
  },
  plugins: [
    // Initializes the plugin with default options, loading the root tsconfig.json
    new ReactDocgenTypescriptPlugin(),
    // Alternatively, specify a custom tsconfig path
    // new ReactDocgenTypescriptPlugin({ tsconfigPath: './tsconfig.build.json' }),
    // Or pass specific TypeScript compiler options directly
    // new ReactDocgenTypescriptPlugin({ compilerOptions: { jsx: ts.JsxEmit.Preserve } }),
  ],
};

export default config;

view raw JSON →