Skip to content

Latest commit

 

History

History
149 lines (102 loc) · 6.24 KB

README.md

File metadata and controls

149 lines (102 loc) · 6.24 KB

Storybook Docs for React

migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the migration guide if you want to migrate to this format of configuring storybook.

Storybook Docs transforms your Storybook stories into world-class component documentation. Storybook Docs for React supports DocsPage for auto-generated docs, and MDX for rich long-form docs.

To learn more about Storybook Docs, read the general documentation. To learn the React specifics, read on!

Installation

First add the package. Make sure that the versions for your @storybook/* packages match:

yarn add -D @storybook/addon-docs

Then add the following to your .storybook/main.js list of addons:

export default {
  // other settings
  addons: ['@storybook/addon-docs'];
}

DocsPage

When you install docs you should get basic DocsPage documentation automagically for all your stories, available in the Docs tab of the Storybook UI.

Props tables

Storybook Docs automatically generates Props tables for your components based on either PropTypes or TypeScript types. To show the props table for your component, be sure to fill in the component field in your story metadata:

import { Button } from './Button';

export default {
  title: 'Button',
  component: Button,
};

If you haven't upgraded from storiesOf, you can use a parameter to do the same thing:

import { storiesOf } from '@storybook/react';
import { Button } from './Button';

storiesOf('InfoButton', module)
  .addParameters({ component: Button })
  .add( ... );

MDX

MDX is a convenient way to document your components in Markdown and embed documentation components, such as stories and props tables, inline.

Then update your .storybook/main.js to make sure you load MDX files:

export default {
  stories: ['../src/stories/**/*.stories.@(js|mdx)'],
};

Finally, you can create MDX files like this:

import { Meta, Story, ArgsTable } from '@storybook/addon-docs';
import { Button } from './Button';

<Meta title='Button' component={Button} />

# Button

Some **markdown** description, or whatever you want.

<Story name='basic' height='400px'>
  <Button>Label</Button>
</Story>

## ArgsTable

<ArgsTable of={Button} />

Inline stories

Storybook Docs renders all React stories inline by default.

However, you can render stories in an iframe, with a default height of 60px (configurable using the docs.story.iframeHeight story parameter), by using the docs.stories.inline parameter.

To do so for all stories, update .storybook/preview.js:

export const parameters = { docs: { story: { inline: false } } };

TypeScript props with react-docgen-typescript

If you're using TypeScript, there are two different options for generating props: react-docgen (default) or react-docgen-typescript.

You can add the following lines to your .storybook/main.js to switch between the two (or disable docgen):

export default {
  typescript: {
    // also valid 'react-docgen' | false
    reactDocgen: 'react-docgen-typescript',
  },
};

Neither option is perfect, so here's everything you should know if you're thinking about using react-docgen for TypeScript.

react-docgen-typescript react-docgen
Features Great. The analysis produces great results which gives the best props table experience. OK. React-docgen produces basic results that are fine for most use cases.
Performance Slow. It's doing a lot more work to produce those results, and may also have an inefficient implementation. Blazing fast. Adding it to your project increases build time negligibly.
Bugs Some. There are corner cases that are not handled properly, and are annoying for developers. Some. There are corner cases that are not handled properly, and are annoying for developers.
SB docs Good. Our prop tables have supported react-docgen-typescript results from the beginning, so it's relatively stable. OK. There are some obvious improvements to fully support react-docgen, and they're coming soon.

Performance is a common question, so here are build times from a random project to quantify. Your mileage may vary:

Docgen Build time
react-docgen-typescript 33s
react-docgen 29s
none 28s

More resources

Want to learn more? Here are some more articles on Storybook Docs: