@nrwl/storybook

Storybook is a development environment for UI components. It allows you to browse a component library, view the different states of each component, and interactively develop and test components.

This guide will briefly walk you through using Storybook within an Nx workspace.

Try out Storybook 7 beta

Storybook version 7 is still in beta. However, you can try it out with Nx by following the instructions in the Storybook 7 setup guide.

Setting Up Storybook

Add the Storybook plugin

yarn add -D @nrwl/storybook

Using Storybook

Generating Storybook Configuration

You can generate Storybook configuration for an individual project with this command:

nx g @nrwl/storybook:configuration project-name

You can choose to use Storybook for one of the supported frameworks:

  • @storybook/angular
  • @storybook/react
  • @storybook/react-native
  • @storybook/html
  • @storybook/web-components
  • @storybook/vue
  • @storybook/vue3
  • @storybook/svelte

Choosing one of these frameworks will have the following effects on your workspace:

  1. Nx will install all the required Storybook packages that go with it.

  2. Nx will generate a root .storybook folder and a project-level .storybook folder (located under libs/your-project/.storybook or apps/your-project/.storybook) containing the essential configuration files for Storybook.

  3. If you are working on an Angular, a React or a React Native project (and you choose @storybook/angular, @storybook/react or @storybook/react-native) the Nx generator will also generate stories for all the components in your project.

  4. Nx will create new targets in your project's project.json, called storybook and build-storybook, containing all the necessary configuration to serve and build Storybook.

  5. Nx will generate a new Cypress e2e app for your project (if there isn't one already) to run against the Storybook instance.

Configure your project using TypeScript

You can choose to configure your project using TypeScript instead of JavaScript. To do that, just add the --tsConfiguration=true flag to the above command, like this:

nx g @nrwl/storybook:configuration project-name --tsConfiguration=true

Here is the Storybook documentation if you want to learn more.

Running Storybook

Serve Storybook using this command:

nx run project-name:storybook

or

nx storybook project-name

Building Storybook

Build Storybook using this command:

nx run project-name:build-storybook

or

nx build-storybook project-name

Anatomy of the Storybook setup

When running the Nx Storybook generator, it'll configure the Nx workspace to be able to run Storybook seamlessly. It'll create

  • a global Storybook configuration
  • a project specific Storybook configuration

The global Storybook configuration allows to set addon-ons or custom webpack configuration at a global level that applies to all Storybook's within the Nx workspace. You can find that folder at .storybook/ at the root of the workspace.

<workspace name>/ ├── .storybook/ │ ├── main.js │ ├── tsconfig.json ├── apps/ ├── libs/ ├── nx.json ├── package.json ├── README.md └── etc...

The project-specific Storybook configuration is pretty much similar what you would have for a non-Nx setup of Storybook. There's a .storybook folder within the project root folder.

<project root>/ ├── .storybook/ │ ├── main.js │ ├── preview.js │ ├── tsconfig.json ├── src/ ├── README.md ├── tsconfig.json └── etc...

Using Addons

To register a Storybook addon for all storybook instances in your workspace:

  1. In /.storybook/main.js, in the addons array of the module.exports object, add the new addon:

    /.storybook/main.js
    module.exports = { stories: [...], ..., addons: [..., '@storybook/addon-essentials'], };

  2. If a decorator is required, in each project's <project-path>/.storybook/preview.js, you can export an array called decorators.

    <project-path>/.storybook/preview.js
    import someDecorator from 'some-storybook-addon'; export const decorators = [someDecorator];

-- OR --

To register an addon for a single storybook instance, go to that project's .storybook folder:

  1. In main.js, in the addons array of the module.exports object, add the new addon:

    module.exports = { stories: [...], ..., addons: [..., '@storybook/addon-essentials'], };

  2. If a decorator is required, in preview.js you can export an array called decorators.

    import someDecorator from 'some-storybook-addon'; export const decorators = [someDecorator];

More Documentation

You can find dedicated information for React and Angular:

You can find all Storybook-related Nx documentation here.

For more on using Storybook, see the official Storybook documentation.

Migration Scenarios

Here's more information on common migration scenarios for Storybook with Nx. For Storybook specific migrations that are not automatically handled by Nx please refer to the official Storybook page

Package reference

Here is a list of all the executors and generators available from this package.

Guides

Executors

Generators

  • initInternal

    Add Storybook configuration to the workspace.

  • configuration

    Add Storybook configuration to a UI library or an application.

  • cypress-project

    Add cypress e2e app to test a UI library that is set up for Storybook.

  • change-storybook-targets

    Change storybook targets for Angular projects to use @storybook/angular executors