UNPKG

7.57 kBMarkdownView Raw
1<center>
2 <img src="../docs/media/docspage-hero.png" width="100%" />
3</center>
4
5<h1>Storybook Docs for React</h1>
6
7> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
8
9Storybook Docs transforms your Storybook stories into world-class component documentation. Storybook Docs for React supports [DocsPage](../docs/docspage.md) for auto-generated docs, and [MDX](../docs/mdx.md) for rich long-form docs.
10
11To learn more about Storybook Docs, read the [general documentation](../README.md). To learn the React specifics, read on!
12
13- [Installation](#installation)
14- [DocsPage](#docspage)
15- [Props tables](#props-tables)
16- [MDX](#mdx)
17- [Inline stories](#inline-stories)
18- [TypeScript props with `react-docgen`](#typescript-props-with-react-docgen)
19- [More resources](#more-resources)
20
21## Installation
22
23First add the package. Make sure that the versions for your `@storybook/*` packages match:
24
25```sh
26yarn add -D @storybook/addon-docs
27```
28
29Then add the following to your `.storybook/main.js` list of `addons`:
30
31```js
32export default {
33 // other settings
34 addons: ['@storybook/addon-docs'];
35}
36```
37
38## DocsPage
39
40When you [install docs](#installation) you should get basic [DocsPage](../docs/docspage.md) documentation automagically for all your stories, available in the `Docs` tab of the Storybook UI.
41
42## Props tables
43
44Storybook Docs automatically generates [Props tables](../docs/props-tables.md) 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:
45
46```ts
47import { Button } from './Button';
48
49export default {
50 title: 'Button',
51 component: Button,
52};
53```
54
55If you haven't upgraded from `storiesOf`, you can use a parameter to do the same thing:
56
57```ts
58import { storiesOf } from '@storybook/react';
59import { Button } from './Button';
60
61storiesOf('InfoButton', module)
62 .addParameters({ component: Button })
63 .add( ... );
64```
65
66## MDX
67
68[MDX](../docs/mdx.md) is a convenient way to document your components in Markdown and embed documentation components, such as stories and props tables, inline.
69
70Then update your `.storybook/main.js` to make sure you load MDX files:
71
72```js
73export default {
74 stories: ['../src/stories/**/*.stories.@(js|mdx)'],
75};
76```
77
78Finally, you can create MDX files like this:
79
80```md
81import { Meta, Story, ArgsTable } from '@storybook/addon-docs';
82import { Button } from './Button';
83
84<Meta title='Button' component={Button} />
85
86# Button
87
88Some **markdown** description, or whatever you want.
89
90<Story name='basic' height='400px'>
91 <Button>Label</Button>
92</Story>
93
94## ArgsTable
95
96<ArgsTable of={Button} />
97```
98
99## Inline stories
100
101Storybook Docs renders all React stories inline by default.
102
103However, 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.
104
105To do so for all stories, update `.storybook/preview.js`:
106
107```js
108export const parameters = { docs: { story: { inline: false } } };
109```
110
111## TypeScript props with `react-docgen`
112
113If you're using TypeScript, there are two different options for generating props: `react-docgen-typescript` (default) or `react-docgen`.
114
115You can add the following lines to your `.storybook/main.js` to switch between the two (or disable docgen):
116
117```js
118export default {
119 typescript: {
120 // also valid 'react-docgen-typescript' | false
121 reactDocgen: 'react-docgen',
122 },
123};
124```
125
126Neither option is perfect, so here's everything you should know if you're thinking about using `react-docgen` for TypeScript.
127
128| | `react-docgen-typescript` | `react-docgen` |
129| --------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
130| **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. |
131| **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. |
132| **Bugs** | **Many**. There are a lot of corner cases that are not handled properly, and are annoying for developers. | **Few**. But there's a dealbreaker, which is lack for imported types (see below). |
133| **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. |
134
135**Performance** is a common question, so here are build times from a random project to quantify. Your mileage may vary:
136
137| Docgen | Build time |
138| ----------------------- | ---------- |
139| react-docgen-typescript | 33s |
140| react-docgen | 29s |
141| none | 28s |
142
143The biggest limitation of `react-docgen` is lack of support for imported types. What that means is that when a component uses a type defined in another file or package, `react-docgen` is unable to extract props information for that type.
144
145```tsx
146import React, { FC } from 'react';
147import SomeType from './someFile';
148
149type NewType = SomeType & { foo: string };
150const MyComponent: FC<NewType> = ...
151```
152
153So in the previous example, `SomeType` would simply be ignored! There's an [open PR for this in the `react-docgen` repo](https://github.com/reactjs/react-docgen/pull/352) which you can upvote if it affects you.
154
155Another common pitfall when switching to `react-docgen` is [lack of support for `React.FC`](https://github.com/reactjs/react-docgen/issues/387). This means that the following common pattern **DOESN'T WORK**:
156
157```tsx
158import React, { FC } from 'react';
159interface IProps { ... };
160const MyComponent: FC<IProps> = ({ ... }) => ...
161```
162
163Fortunately, the following workaround works:
164
165```tsx
166const MyComponent: FC<IProps> = ({ ... }: IProps) => ...
167```
168
169Please upvote [the issue](https://github.com/reactjs/react-docgen/issues/387) if this is affecting your productivity, or better yet, submit a fix!
170
171## More resources
172
173Want to learn more? Here are some more articles on Storybook Docs:
174
175- References: [DocsPage](../docs/docspage.md) / [MDX](../docs/mdx.md) / [FAQ](../docs/faq.md) / [Recipes](../docs/recipes.md) / [Theming](../docs/theming.md) / [Props](../docs/props-tables.md)
176- Announcements: [Vision](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a) / [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf) / [MDX](https://medium.com/storybookjs/rich-docs-with-storybook-mdx-61bc145ae7bc) / [Framework support](https://medium.com/storybookjs/storybook-docs-for-new-frameworks-b1f6090ee0ea)
177- Example: [Storybook Design System](https://github.com/storybookjs/design-system)