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.

Storybook 7 by default

Starting with Nx 16, Storybook 7 is used by default to configure your projects.

Setting Up Storybook

Add the Storybook plugin

Keep Nx Package Versions In Sync

Make sure to install the @nx/storybook version that matches the version of nx in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can fix Nx version mismatches with this recipe.

❯

yarn add -D @nx/storybook

Nx 15 and lower use @nrwl/ instead of @nx/

Using Storybook

Generating Storybook Configuration

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

❯

nx g @nx/storybook:configuration project-name

Nx 15 and lower use @nrwl/ instead of @nx/

If you are NOT using a framework-specific generator (for Angular, React, React Native), in the field uiFramework you must choose one of the following Storybook frameworks:

  • @storybook/angular
  • @storybook/html-webpack5
  • @storybook/nextjs
  • @storybook/preact-webpack5
  • @storybook/react-webpack5
  • @storybook/react-vite
  • @storybook/server-webpack5
  • @storybook/svelte-webpack5
  • @storybook/svelte-vite
  • @storybook/sveltekit
  • @storybook/vue-webpack5
  • @storybook/vue-vite
  • @storybook/vue3-webpack5
  • @storybook/vue3-vite
  • @storybook/web-components-webpack5
  • @storybook/web-components-vite

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 project-level .storybook folder (located under libs/your-project/.storybook or apps/your-project/.storybook) containing the essential configuration files for Storybook.

  3. 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.

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

Make sure to use the framework-specific generators if your project is using Angular, React, Next.js or React Native: @nx/angular:storybook-configuration, @nx/react:storybook-configuration, @nx/react-native:storybook-configuration:

❯

nx g @nx/angular:storybook-configuration my-angular-project

Nx 15 and lower use @nrwl/ instead of @nx/

These framework-specific generators will also generate stories for you.

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 @nx/storybook:configuration project-name --tsConfiguration=true

Nx 15 and lower use @nrwl/ instead of @nx/

Here is the Storybook documentation if you want to learn more about configuring your project with TypeScript.

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 project specific Storybook configuration.

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

1<project root>/ 2├── .storybook/ 3│ ├── main.js 4│ ├── preview.js 5│ ├── tsconfig.json 6├── src/ 7├── README.md 8├── tsconfig.json 9└── etc... 10

Using Addons

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

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

    <project-path>/.storybook/main.js
    1module.exports = { 2stories: [...], 3..., 4addons: [..., '@storybook/addon-essentials'], 5}; 6

  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
    1import someDecorator from 'some-storybook-addon'; 2export const decorators = [someDecorator]; 3

Setting up documentation

To set up documentation, you can use Storybook Autodocs. For Angular, you can use compodoc to infer argTypes. You can read more about argTypes in the official Storybook argTypes documentation.

You can read more about how to best set up documentation using Storybook for your project in the official Storybook documentation.

More Documentation

You can find dedicated information for React and Angular:

You can find all Storybook-related Nx documentation in the Storybook recipes section.

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

Older documentation

You can find older documentation for the @nx/storybook package in our deprecated section.