FAQ

[transitive-bullshit]

Why would I want to use docz if I'm already using Storybook?

Storybook's pretty great. Writing "stories" at the component level is a very powerful abstraction, and it has benefitted from enormous popularity within the React community.

Storybook does, however, have some flaws. The docs generally provide a great developer experience but are not ideal for design systems targeting designers or other business stakeholders. Storybook sites also tend to look pretty boring and you can't currently use MDX, a transformative technology that makes writing documentation in addition to component demos extremely fast and concise.

This is where Docz comes in -- it's already a really popular project that allows developers to write better component docs faster.

If your project is aiming to be a design system, as opposed to just a development tool, then Docz will give you a lot more flexibility & power towards that end.

---

Do I have to switch away from Storybook?

Not at all -- this plugin allows you to continue using Storybook as a development environment if you choose to. It just allows you to surface your existing stories from within Docz as a simple migration path. If you want to, there's no reason you can't use the two projects hand-in-hand, with Storybook providing a great developer experience and Docz providing a great public experience aimed at devs and non-devs alike.

---

My project uses storybook with custom webpack or babel configs. How can I get these to work with docz?

Currently, these will likely not work out of the box with this plugin. See #8 for more details about the work needed to make this use case "just work".

---

Storybook wraps each story in an iframe for isolation. Can I do something similar with Docz?

Yes! We provide an option to wrap each of your stories in a storyWrapper, which may be an iframe, a shadow dom, or your own custom wrapper.

You may use the following example for reference which wraps all stories in iframes courtesy of react-frame-component.

• create a story wrapper component
• pass in the path to the wrapper in the storybook config

// story-wrapper.js
import Frame from 'react-frame-component'

export default ({ children, style = {}, ...rest }) => (
  <Frame
    style={{
      width: 320,
      ...style
    }}
    {...rest}
  >
    {children}
  </Frame>
)

// doczrc.js
import { storybook } from 'docz-plugin-storybook'

export default {
  plugins: [storybook({ storyWrapper: './story-wrapper' })]
}

---

How does this plugin work?

1. Add the storybook entrypoint as an additional webpack entry in Docz's config.
2. Alias @storybook/react to a minimal shim that replaces Storybook's built-in UX with logic to aggregate story metadata as their storiesOf and .add are called. This shim matches @storybook/react's public exports exactly, so any existing Storybook code will continue to work.
3. Docz's client-side code executes which initializes our all of the stories.
4. In the case of automatic rendering, we take all of the aggregated stories and add them to Docz's contents via mdx files in .docz/storybook/.
5. In the case of manual rendering, whenever a Story or multiple Stories are rendered, these components look up the target stories in our shim's store and invoke their renderer which produces a normal React subtree.
6. Profit!

TODO: provide more detail on steps 4 and 5.

[transitive-bullshit]

Note: this list is an active WIP and should be added somewhere more final than in a GH issue.

Please suggest additional questions & answers here.