Nx Storybook Plugin Overview

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.

Setting Up Storybook

Installation

In any Nx workspace, you can install @nx/storybook by running the following command:

nx add @nx/storybook

This will install the correct version of @nx/storybook.

How @nx/storybook Infers Tasks

The @nx/storybook plugin will create a task for any project that has a Storybook configuration file present. Any of the following files will be recognized as a Storybook configuration file:

.storybook/main.js
.storybook/main.ts
.storybook/main.cjs
.storybook/main.cts
.storybook/main.mjs
.storybook/main.mts

View Inferred Tasks

To view inferred tasks for a project, open the project details view in Nx Console or run nx show project my-project --web in the command line.

@nx/storybook Configuration

The @nx/storybook/plugin is configured in the plugins array in nx.json.

{
  "plugins": [
    {
      "plugin": "@nx/storybook/plugin",
      "options": {
        "buildStorybookTargetName": "build-storybook",
        "serveStorybookTargetName": "storybook",
        "testStorybookTargetName": "test-storybook",
        "staticStorybookTargetName": "static-storybook"
      }
    }
  ]
}

The builtStorybookTargetName, serveStorybookTargetName, testStorybookTargetName and staticStorybookTargetName options control the names of the inferred Storybook tasks. The default names are build-storybook, storybook, test-storybook and static-storybook.

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 g @nx/angular:storybook-configuration my-angular-project

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

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

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

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

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

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

Nx will install all the required Storybook packages that go with it.
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.
Nx will create new targets in your project's project.json, called storybook, test-storybook and build-storybook, containing all the necessary configuration to serve, test and build Storybook.

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

Running Storybook

Serve Storybook using this command:

nx run project-name:storybook

nx storybook project-name

Building Storybook

Build Storybook using this command:

nx run project-name:build-storybook

nx build-storybook project-name

Testing Storybook

With the Storybook server running, you can test Storybook (run all the interaction tests) using this command:

nx run project-name:test-storybook

nx test-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.

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

Using Addons

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

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

// <project-path>/.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  ...
  addons: ['@storybook/addon-essentials', '@storybook/addon-interactions', ...],
  ...
};

export default config;

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

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

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.