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.

How to Use Storybook in an Nx Repo

Add the Storybook plugin

yarn add --dev @nrwl/storybook

Generating Storybook Configuration

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

nx g @nrwl/angular:storybook-configuration project-name

If there's no .storybook folder at the root of the workspace, one is created.

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

Also, a project-specific .storybook folder is added in the root of the project.

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

Running Storybook

Serve Storybook using this command:

nx run project-name:storybook

Auto-generate Stories

The @nrwl/angular:storybook-configuration generator has the option to automatically generate *.stories.ts files for each component declared in the library.

<some-folder>/
├── my.component.ts
└── my.component.stories.ts

Run Cypress Tests Against a Storybook Instance

Both 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=buttoncomponent--primary&args=text:Click+me!;padding;style:default'

• buttoncomponent is a lowercase version of the Title in the *.stories.ts file.
• primary is the name of an individual story.
• style=default sets the style arg to a value of default.

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

*.component.stories.ts file

1import { moduleMetadata, Story, Meta } from '@storybook/angular';
2import { ButtonComponent } from './button.component';
3
4export default {
5  title: 'ButtonComponent',
6  component: ButtonComponent,
7  decorators: [
8    moduleMetadata({
9      imports: [],
10    }),
11  ],
12} as Meta<ButtonComponent>;
13
14const Template: Story<ButtonComponent> = (args: ButtonComponent) => ({
15  component: ButtonComponent,
16  props: args,
17});
18
19export const Primary = Template.bind({});
20Primary.args = {
21  text: 'Click me!',
22  padding: 0,
23  style: 'default',
24};

Cypress *.spec.ts file

1describe('shared-ui', () => {
2  beforeEach(() =>
3    cy.visit(
4      '/iframe.html?id=buttoncomponent--primary&args=text:Click+me!;padding;style:default'
5    )
6  );
7
8  it('should render the component', () => {
9    cy.get('storybook-trial-button').should('exist');
10  });
11});

Using Addons

To register an 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:

   Copy

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

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

   Copy

   1import someDecorator from 'some-storybook-addon';
   2export 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:

   Copy

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

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

   Copy

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

Migrations

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

More Information

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