Set up Storybook for React Projects
This guide will walk you through setting up Storybook for React projects in your Nx workspace.
Set up Storybook in your workspaceYou first need to set up Storybook for your Nx workspace, if you haven't already. You can read the Storybook plugin overview guide to get started.
Generate Storybook Configuration for a React project
You can generate Storybook configuration for an individual React project by using the @nx/react:storybook-configuration generator, like this:
❯
nx g @nx/react:storybook-configuration project-name
Nx React Storybook Preset
The @nx/react package ships with a Storybook addon to make sure it uses the very same configuration as your Nx React application. When you generate a Storybook configuration for a project, it'll automatically add the addon to your configuration.
1module.exports = {
2 ...
3 addons: ['@storybook/addon-essentials', ..., '@nx/react/plugins/storybook'],
4 ...
5};
6Auto-generate Stories
The @nx/react:storybook-configuration generator has the option to automatically generate *.stories.ts|tsx files for each component declared in the library. The stories will be generated using Component Story Format 3 (CSF3).
1<some-folder>/
2├── my-component.tsx
3└── my-component.stories.tsx
4If you add more components to your project, and want to generate stories for all your (new) components at any point, you can use the @nx/react:stories generator:
❯
nx g @nx/react:stories --project=<project-name>
Let's take for a example a library in your workspace, under libs/feature/ui, called feature-ui. This library contains a component, called my-button.
The command to generate stories for that library would be:
❯
nx g @nx/react:stories --project=feature-ui
and the result would be the following:
1<workspace name>/
2├── apps/
3├── libs/
4│ ├── feature/
5│ │ ├── ui/
6| | | ├── .storybook/
7| | | ├── src/
8| | | | ├──lib
9| | | | | ├──my-button
10| | | | | | ├── my-button.tsx
11| | | | | | ├── my-button.stories.tsx
12| | | | | | └── etc...
13| | | | | └── etc...
14| | | ├── README.md
15| | | ├── tsconfig.json
16| | | └── etc...
17| | └── etc...
18| └── etc...
19├── nx.json
20├── package.json
21├── README.md
22└── etc...
23Cypress tests for Stories
The @nx/react:storybook-configuration generator gives the option to set up an e2e Cypress app that is configured to run against the project's Storybook instance.
To launch Storybook and run the Cypress tests against the iframe inside of Storybook:
❯
nx run project-name-e2e:e2e
The url that Cypress points to should look like this:
'/iframe.html?id=mybutton--primary&args=text:Click+me!;padding;style:default'
buttoncomponentis a lowercase version of theTitlein the*.stories.tsxfile.primaryis the name of an individual story.style=defaultsets thestylearg to a value ofdefault.
Changing args in the url query parameters allows your Cypress tests to test different configurations of your component. You can read the documentation for more information.
Example Files
Let's take for a example a library in your workspace, under libs/feature/ui, called feature-ui with a component, called my-button.
Story file
The @nx/react:storybook-configuration generator would generate a Story file that looks like this:
1import type { Meta } from '@storybook/react';
2import { MyButton } from './my-button';
3
4const Story: Meta<typeof MyButton> = {
5 component: MyButton,
6 title: 'MyButton',
7};
8export default Story;
9
10export const Primary = {
11 args: {
12 text: 'Click me!',
13 padding: 10,
14 disabled: true,
15 },
16};
17Cypress test file
For the library described above, Nx would generate an E2E project called feature-ui-e2e with a Cypress test file that looks like this:
1describe('feature-ui: MyButton component', () => {
2 beforeEach(() =>
3 cy.visit(
4 '/iframe.html?id=mybutton--primary&args=text:Click+me!;padding;style:default'
5 )
6 );
7
8 it('should contain the right text', () => {
9 cy.get('button').should('contain', 'Click me!');
10 });
11});
12Depending on your Cypress version, the file will end with .spec.ts or .cy.ts.
More Documentation
You can find all Storybook-related Nx topics 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