React-styleguidist: Comparison with Storybook

[oyeanuj]

Hi folks! This is more of a docs question rather than an issue - feel free to close it if inappropriate. I was looking to decide between Storybook and StyleGuidist.

So, I was wondering if anyone had a perspective on the pros/cons between the two choices given that people using it have a better idea about this library?

[sapegin]

It is of course very appropriate — both tools are great ;-)

Here’s a quote from my article on component driven development (in draft now):

React Storybook v. React Styleguidist

Both tools are good and mature, they have many similarities but also some distinctions that may make you choose one or the other. For me the biggest distinction is how you describe component variations.

With Storybook you write stories in JavaScript files:

import React from 'react';
import { storiesOf } from '@storybook/react';
import { action } from '@storybook/addon-actions';
import Button from '../components/Button';

storiesOf('Button', module)
  .add('default', () => (
    <Button onClick={action('clicked')}>Push Me</Button>
  ))
  .add('large size', () => (
    <Button size="large">Push Me</Button>
  ));

And with Styleguidist you write examples in Markdown files:

React button component example:

```js
<Button onClick={() => console.log('clicked')>Push Me</Button>
```

Large size:

```js
<Button size="large">Push Me</Button>
```

Another important distinction is that Storybook shows only one variation of one component at a time but Styleguidist can show all variations of all components, all variations of a single component or one variation.

| Feature | Storybook | Styleguidist |
|:--|:--|:--|
| Component examples | JavaScript | Markdown |
| Props docs | Yes | Yes |
| Public methods docs | No | Yes |
| Style guide | No | Yes |
| Customizable design | No | Yes |
| Extra documentation | No | Yes |
| Plugins | Many | No¹ |

¹ In development.

---

Do you have any ideas where would be the right place in the docs for that?

Also anyone — feel free to improve my explanation or point me where I’m wrong.

[oyeanuj]

@sapegin Thank you for the quick and detailed response! It also seems like that styleguidist supports nested components and storybook doesn't? If yes, that could be another thing to add.

I'd suggest adding it around the Usage section (maybe after Cookbook) in the README as this is information that folks would need as to better understand the library.

[sapegin]

It also seems like that styleguidist supports nested components and storybook doesn't?

I think now Storybook has this too.

[jrwebdev]

We use both where I work. Storybook we use for displaying the multiple different states of our components and can tailor the stories to aid in testing and development. Styleguidist we use for formal documentation and demos of our public components.

Both are great tools, but I personally see them as having different uses, especially if you're using them in a larger company.

[tizmagik]

Good explanation and breakdown @sapegin -- +1 for adding this to the docs. I get this question a lot internally.

[tizmagik]

Also for this:

Feature | Storybook | Styleguidist
-- | -- | --
Style guide | No | Yes

I think that's debatable. The docs that Storybook produces can also be seen as a styleguide. I would put "Yes" in both columns there IMO.

[sapegin]

@tizmagik I’d put No with an asterisk ;-)

[tizmagik]

Haha fair enough :)

[skywalkerlw]

storybook support react native, how about styleguidist?

[gouegd]

Another important distinction is that Storybook shows only one variation of one component at a time but Styleguidist can show all variations of all components, all variations of a single component or one variation.

I think on the contrary this is unimportant as it is very simple to dynamically create a story containing all other stories for a given component (I do this for all my components and this appears as the first story)

I think both tools are cool and hopefully can coexist peacefully ;)

[alzalabany]

can we setup custom testing cose with styleguidist ?
storybook you can prepare mock data using faker run beforeAll or beforeEach to wrap component with context Parent for examplr.

how can we do this in markdown ?