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
Add the Storybook plugin
Keep Nx Package Versions In SyncMake 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
Using Storybook
Generating Storybook Configuration
You can generate Storybook configuration for an individual project with this command:
❯
nx g @nx/storybook:configuration project-name
or
❯
nx g @nx/angular:storybook-configuration my-angular-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, React Native, Vue, Nuxt), 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:
Nx will install all the required Storybook packages that go with it.
Nx will generate a project-level
.storybookfolder (located underlibs/your-project/.storybookorapps/your-project/.storybook) containing the essential configuration files for Storybook.Nx will create new
targetsin your project'sproject.json, calledstorybook,test-storybookandbuild-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, @nx/nuxt:storybook-configuration, @nx/react-native:storybook-configuration, as shown above.
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
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
or
❯
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.
1<project root>/
2├── .storybook/
3│ ├── main.ts
4│ └── preview.ts
5├── src/
6├── README.md
7├── tsconfig.json
8├── tsconfig.storybook.json
9└── etc...
10Using Addons
To register a Storybook addon for all Storybook instances in your workspace:
- In your project's
.storybook/main.tsfile, in theaddonsarray of themodule.exportsobject, add the new addon:
1import type { StorybookConfig } from '@storybook/react-vite';
2
3const config: StorybookConfig = {
4 ...
5 addons: ['@storybook/addon-essentials', '@storybook/addon-interactions', ...],
6 ...
7};
8
9export default config;
10If a decorator is required, in each project's
<project-path>/.storybook/preview.ts, you can export an array calleddecorators.<project-path>/.storybook/preview.ts1import 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:
- Set up Storybook for Angular Projects
- Set up Storybook for React Projects
- Set up Storybook for Vue Projects
- Set up Storybook for Nuxt Projects
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
- Upgrading to Storybook 6
- Migrate to the Nx React Storybook Addon
- Storybook 7 migration generator
- Storybook 7 setup guide
Older documentation
You can find older documentation for the @nx/storybook package in our deprecated section.