Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
react-docgen-typescript-loader
Advanced tools
Webpack loader to generate docgen information from TypeScript React components.
The react-docgen-typescript-loader is a webpack loader that uses react-docgen-typescript to parse TypeScript React components and generate documentation from them. It is particularly useful for creating documentation for React components written in TypeScript, as it extracts prop types, default values, and descriptions from the TypeScript code.
Generate Documentation
This feature allows you to generate documentation for your TypeScript React components by integrating the react-docgen-typescript-loader into your webpack configuration. The loader will parse your TypeScript files and extract documentation information.
module.exports = {
module: {
rules: [
{
test: /\.tsx?$/,
use: [
{
loader: 'react-docgen-typescript-loader',
options: {
// Options for react-docgen-typescript
}
}
]
}
]
}
};
Customizing Documentation Output
This feature allows you to customize the output of the documentation by providing options to the react-docgen-typescript-loader. In this example, the propFilter option is used to exclude props coming from node_modules.
module.exports = {
module: {
rules: [
{
test: /\.tsx?$/,
use: [
{
loader: 'react-docgen-typescript-loader',
options: {
propFilter: (prop) => prop.parent ? !/node_modules/.test(prop.parent.fileName) : true
}
}
]
}
]
}
};
react-docgen is a library for extracting information from React components written in JavaScript. It is similar to react-docgen-typescript-loader but does not support TypeScript out of the box. It is useful for projects that use plain JavaScript instead of TypeScript.
react-styleguidist is a tool for generating style guides for React components. It uses react-docgen under the hood to extract component information and can be configured to work with TypeScript. It provides a more comprehensive solution for creating living style guides compared to react-docgen-typescript-loader.
Storybook is a popular tool for developing and showcasing UI components in isolation. It supports both JavaScript and TypeScript and can be configured to use react-docgen or react-docgen-typescript for extracting component documentation. It offers a rich set of features for component development and documentation.
Webpack loader to generate docgen information from TypeScript React components. The primary use case is to get the prop types table populated in the Storybook Info Addon.
Example Storybook project
Live Storybook
View Changelog.
Version 2 supported the options includes
and excludes
, which were arrays of regular expressions. If you made use of these options, remove them from and use the Webpack equivalents.
includes
would default to ["\\.tsx$"]
which meant that only files ending in the extension .ts
or .tsx
would be processed. This default behavior is already covered by Webpack's test
field.
excludes
would default to ["node_modules"]
. This would prevent the processing of files in node_modules. This option was added to allow further filtering to hopefully speed up processing. When this loader is used in monorepo environments, this option would complicate configuration.
In version 3, the loader no longer performs its own filtering. If you relied on the additional filtering behavior, you should be able to reimplement it using options in Webpack.
This change shouldn't affect the majority of projects.
The source code generation relies on being able to insert // @ts-ignore
in a few select places and as such requires TypeScript 2.3 or above.
$ npm install --save-dev react-docgen-typescript-loader
or
$ yarn add --dev react-docgen-typescript-loader
IMPORTANT: Webpack loaders are executed right-to-left (or bottom-to-top). react-docgen-typescript-loader
needs to be added under ts-loader
.
Example Storybook config /.storybook/webpack.config.js
:
const path = require("path");
module.exports = (baseConfig, env, config) => {
config.module.rules.push({
test: /\.tsx?$/,
include: path.resolve(__dirname, "../src"),
use: [
require.resolve("ts-loader"),
{
loader: require.resolve("react-docgen-typescript-loader"),
options: {
// Provide the path to your tsconfig.json so that your stories can
// display types from outside each individual story.
tsconfigPath: path.resolve(__dirname, "../tsconfig.json"),
},
},
],
});
config.resolve.extensions.push(".ts", ".tsx");
return config;
};
const path = require("path");
const genDefaultConfig = require("@storybook/react/dist/server/config/defaults/webpack.config.js");
module.exports = (baseConfig, env) => {
const config = genDefaultConfig(baseConfig);
config.module.rules.push({
test: /\.tsx?$/,
include: path.resolve(__dirname, "../src"),
use: [
require.resolve("ts-loader"),
{
loader: require.resolve("react-docgen-typescript-loader"),
options: {
// Provide the path to your tsconfig.json so that your stories can
// display types from outside each individual story.
tsconfigPath: path.resolve(__dirname, "../tsconfig.json"),
},
},
],
});
config.resolve.extensions.push(".ts", ".tsx");
return config;
};
Include the withInfo
decorator as normal.
Reference the addon documentation for the latest usage instructions:
https://github.com/storybooks/storybook/tree/master/addons/info
The Storybook Info Addon is able to populate the component description from your component's documentation. It does this when your story name matches the display name of your component. The prop tables will populate in either case.
In the first example you are able to see above Story Source
the component description. The second example shows a story with a name different from the component. In the second example the component description is missing.
If you have a component named
TicTacToeCell
, then you would have to use something like: storiesOf("...", module).add("TicTacToeCell", ...)
to have the story description come from the component description.
In addition to the description from the component, you may still include story description text using the normal withInfo api.
It is important to export your component using a named export for docgen information to be generated properly.
TicTacToeCell.tsx
:
import React, { Component } from "react";
import * as styles from "./TicTacToeCell.css";
interface Props {
/**
* Value to display, either empty (" ") or "X" / "O".
*
* @default " "
**/
value?: " " | "X" | "O";
/** Cell position on game board. */
position: { x: number, y: number };
/** Called when an empty cell is clicked. */
onClick?: (x: number, y: number) => void;
}
/**
* TicTacToe game cell. Displays a clickable button when the value is " ",
* otherwise displays "X" or "O".
*/
// Notice the named export here, this is required for docgen information
// to be generated correctly.
export class TicTacToeCell extends Component<Props> {
handleClick = () => {
const {
position: { x, y },
onClick,
} = this.props;
if (!onClick) return;
onClick(x, y);
};
render() {
const { value = " " } = this.props;
const disabled = value !== " ";
const classes = `${styles.button} ${disabled ? styles.disabled : ""}`;
return (
<button
className={classes}
disabled={disabled}
onClick={this.handleClick}
>
{value}
</button>
);
}
}
// Component can still be exported as default.
export default TicTacToeCell;
ColorButton.stories.tsx
:
import React from "react";
import { storiesOf } from "@storybook/react";
import { withInfo } from "@storybook/addon-info";
import { action } from "@storybook/addon-actions";
import TicTacToeCell from "./TicTacToeCell";
const stories = storiesOf("Components", module);
stories.add(
"TicTacToeCell",
withInfo({ inline: true })(() => (
<TicTacToeCell
value="X"
position={{ x: 0, y: 0 }}
onClick={action("onClick")}
/>
)),
);
Option | Type | Description |
---|---|---|
skipPropsWithName | string[] or string | Avoid including docgen information for the prop or props specified. |
skipPropsWithoutDoc | boolean | Avoid including docgen information for props without documentation. |
componentNameResolver | function | If a string is returned, then the component will use that name. Else it will fallback to the default logic of parser. https://github.com/styleguidist/react-docgen-typescript#parseroptions |
propFilter | function | Filter props using a function. If skipPropsWithName or skipPropsWithoutDoc is defined the function will not be used. Function accepts two arguments: object with information about prop and an object with information about component. Return true to include prop in documentation. https://github.com/styleguidist/react-docgen-typescript#parseroptions |
tsconfigPath | string | Specify the location of the tsconfig.json to use. Can not be used with compilerOptions. |
compilerOptions | typescript.CompilerOptions | Specify TypeScript compiler options. Can not be used with tsconfigPath. |
docgenCollectionName | string or null | Specify the docgen collection name to use. All docgen information will be collected into this global object. Set to null to disable. Defaults to STORYBOOK_REACT_CLASSES for use with the Storybook Info Addon. https://github.com/gongreg/react-storybook-addon-docgen |
setDisplayName | boolean | Automatically set the components' display name. If you want to set display names yourself or are using another plugin to do this, you should disable this option. Defaults to true . This is used to preserve component display names during a production build of Storybook. |
shouldExtractLiteralValuesFromEnum | boolean | If set to true, string enums and unions will be converted to docgen enum format. Useful if you use Storybook and want to generate knobs automatically using addon-smart-knobs. https://github.com/styleguidist/react-docgen-typescript#parseroptions |
savePropValueAsString | boolean | If set to true, defaultValue to props will be string. https://github.com/styleguidist/react-docgen-typescript#parseroptions |
typePropName | string | Specify the name of the property for docgen info prop type. |
There is a significant startup cost due to the initial type parsing. Once the project is running in watch mode, things should be smoother due to Webpack caching.
This plugin uses a Webpack loader to inject the docgen information. There is also a version which works as a Webpack plugin. I will be supporting both versions. The loader version more accurately generates the injected code blocks and should work with all module types but at the cost of a longer initial startup. The plugin version may be faster.
The Webpack plugin version is available here: https://github.com/strothj/react-docgen-typescript-loader/tree/plugin
This plugin makes use of the project: https://github.com/styleguidist/react-docgen-typescript. It is subject to the same limitations.
When extending from React.Component
as opposed to Component
, docgens don't seem to be created. Ref issue #10 (thanks @StevenLangbroek for tracking down the cause).
Doesn't work:
import React from 'react';
interface IProps {
whatever?: string;
};
export default class MyComponent extends React.Component<IProps> {}
Works:
import React, { Component } from 'react';
export default class MyComponent extends Component<IProps> {}
Component docgen information can not be generated for components that are only exported as default. You can work around the issue by exporting the component using a named export.
import * as React from "react";
interface ColorButtonProps {
/** Buttons background color */
color: "blue" | "green";
}
/** A button with a configurable background color. */
export const ColorButton: React.SFC<ColorButtonProps> = props => (
<button
style={{
padding: 40,
color: "#eee",
backgroundColor: props.color,
fontSize: "2rem",
}}
>
{props.children}
</button>
);
export default ColorButton;
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
[3.7.2] - 2020-03-29
FAQs
Webpack loader to generate docgen information from TypeScript React components.
The npm package react-docgen-typescript-loader receives a total of 163,543 weekly downloads. As such, react-docgen-typescript-loader popularity was classified as popular.
We found that react-docgen-typescript-loader demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.