✨ Document React components with @prop ✨

react-tsdoc 🤖

react-tsdoc is an tool to extract information from React Typescript component files with TSDoc for documentation generation that elaborates on the TSDoc standard. Just use @prop!

Similar to react-docgen, react-tsdoc is a low level tool to extract information about React components. Use react-tsdoc-loader to inject the docs into Storybook.

Wouldn't it be nice if instead of doing this...

/**
 * Nice button
 */
const Button = ({
	disabled,
	label,
	onClick
}: {
	/**
	 * Disables the button
	 */
	disabled: boolean
	/**
	 * Label for the button
	 */
	label: string
	/**
	 * Fired when button clicked
	 */
	onClick: (...) => {}
}) => ();

You could do this 👇 and still have Storybook pick up the prop descriptions?

/**
 * Nice button
 *
 * @prop disabled - Disables the button
 * @prop label - Label for the button
 * @prop onClick - Fired when button clicked
 */
const Button = ({
	disabled,
	label,
	onClick
}: {
	disabled: boolean
	label: string
	onClick: (...) => {}
}) => ();

That's where react-tsdoc comes in! It automatically generates documentation from the TSDoc comment's @props while also still passing through all the other goodies you also want to see, such as if a prop is required, types, default values, and more!

Install

To install react-tsdoc just run:

npm i -g react-tsdoc

And you can run the parser like:

react-tsdoc ./src/components --output ./docs/output.json

How do I use this with Storybook?

This tool just create JSON blobs with the documentation information. To use this with Storybook you'll need to use the Webpack loader to inject this information into your story's components.

Use react-tsdoc-loader to inject the docs into Storybook.

Why @prop?

Because it looks nicer! I personally perfer seeing the descriptions for all of my component's props right at the top so I can get all of the information I need right at a glance.

Why TSDoc instead of JSDoc?

Great question! Part of the beauty of Typescript is that you explicitely set types, so why would you want to duplicate those in your docs? TSDoc does away with that so you only need to call out your prop name and add a description. Easy!

Output

Here's an example component with the associated parser output...

Input:

/**
 * Button
 *
 * @prop disabled - Sets if field is disabled
 * @prop label - Sets the button text
 */
const Button = ({
	disabled = false,
	label
}: {
	disabled?: boolean
	label: string
}) => {
	return (
		<button disabled={disabled}>
			{label}
		</button>
	)
};

Output:

{
  "description": "Button",
  "props": {
    "disabled": {
      "description": "Sets if field is disabled",
      "required": false,
      "tsType": {
        "name": "boolean"
      },
      "defaultValue": {
        "value": "false",
        "computed": false
      }
    },
    "label": {
      "description": "Sets the button text",
      "required": true,
      "tsType": {
        "name": "string"
      }
    }
  }
}

Adding to tsdoc.json

Adding support for the @prop tag to your TSDoc config is easy! This allows your eslint-plugin-tsdoc to properly parse @prop. Create a tsdoc.json if you don't already have one and add this to it:

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "tagDefinitions": [
    {
      "tagName": "@prop",
      "syntaxKind": "block"
    }
  ]
}

Why another docgen?

Though react-docgen, typedoc, and react-docgen-typescript are all wonderful tools, defining props can be a challenge, especially if you are destructuring props.

As Shilman of Storybook noted in this Gist, Storybook plans to adopt react-docgen for SB7, however react-docgen is based on an outdated Doc parser (doctrine) and does not support the TSDoc standard.

I have found that interface documentation can be rather cumbersome and being able to see what each respective prop is used for at a glance is extremely handy.

Ultimately, this is just an excuse for me to play around with ASTs, but I hope others find some use in this project.

Supported Types

• [x] Simple (foo: string, bar: boolean)
• [x] Literals (foo: 'bar')
• [x] Tuples (foo: [string, number])
• [x] Unions (foo: string | boolean)
• [x] Typed arrays (foo: string[])
• [x] Object signatures ({ foo: string})
• [x] Index signatures ([foo: string]: string)
• [x] Function signatures (foo: (x: string) => void)
• [ ] Intersect (foo: string & number)
• [ ] Nullable modifier (foo: ?number)
• [ ] Typed classes (foo: Class<bar>)

Extended support coming soon.

Development

I've heavily commented a lot of the functions as this has been an AST learning experience for me, and I hope others find it easy to understand and contribute.

To build, just run:

npm install && npm run build

This will build the ./lib folder and then you can execute the CLI from the /bin directory, like this:

bin/react-tsdoc.js ./src/components ./output.json && cat ./output.json

To run the tests:

npm run test