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.

This guide will briefly walk you through using Storybook within an Nx workspace.

Setting Up Storybook

Add the Storybook plugin

yarn add --dev @nrwl/storybook

Using Storybook

Generating Storybook Configuration

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

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

Running Storybook

Serve Storybook using this command:

nx run project-name:storybook

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

The global Storybook configuration allows to set addon-ons or custom webpack configuration at a global level that applies to all Storybook's within the Nx workspace. You can find that folder at .storybook/ at the root of the workspace.

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

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.js
│   ├── preview.js
│   ├── tsconfig.json
├── src/
├── README.md
├── tsconfig.json
└── etc...

Using Addons

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

In /.storybook/main.js, in the addons array of the module.exports object, add the new addon:

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

If a decorator is required, in each project's <project-path>/.storybook/preview.js, you can export an array called decorators.
```
import someDecorator from 'some-storybook-addon';
export const decorators = [someDecorator];
```

-- OR --

To register an addon for a single storybook instance, go to that project's .storybook folder:

In main.js, in the addons array of the module.exports object, add the new addon:

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

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

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

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

You can re-run it at a later point using the following command:

nx g @nrwl/angular:stories <project-name>

Cypress tests for Stories

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

import { moduleMetadata, Story, Meta } from '@storybook/angular';
import { ButtonComponent } from './button.component';

export default {
  title: 'ButtonComponent',
  component: ButtonComponent,
  decorators: [
    moduleMetadata({
      imports: [],
    }),
  ],
} as Meta<ButtonComponent>;

const Template: Story<ButtonComponent> = (args: ButtonComponent) => ({
  props: args,
});

export const Primary = Template.bind({});
Primary.args = {
  text: 'Click me!',
  padding: 0,
  style: 'default',
};

Cypress *.spec.ts file

describe('shared-ui', () => {
  beforeEach(() =>
    cy.visit(
      '/iframe.html?id=buttoncomponent--primary&args=text:Click+me!;padding;style:default'
    )
  );

  it('should render the component', () => {
    cy.get('storybook-trial-button').should('exist');
  });
});

Setting up `projectBuildConfig`

Storybook for Angular needs a default project specified in order to run. The reason is that it uses that default project to read the build configuration from (paths to files to include in the build, and other configurations/settings). In Nx workspaces, that project is specified with the projectBuildConfig property.

If you're using Nx version >=13.4.6 either in a new Nx workspace, or you migrated your older Nx workspace to Nx version >=13.4.6, Nx will automatically add the projectBuildConfig property in your projects project.json files, for projects that are using Storybook. It will look like this:

    "storybook": {
      "executor": "@nrwl/storybook:storybook",
      "options": {
         ...
        "projectBuildConfig": "my-project:build-storybook"
      },
      ...
    },
    "build-storybook": {
      "executor": "@nrwl/storybook:build",
       ...
      "options": {
         ...
        "projectBuildConfig": "my-project:build-storybook"
      },
     ...
    }

This setup instructs Nx to use the configuration under the build-storybook target of my-project when using the storybook and build-storybook executors.

If the projectBuildConfig is not set in your project.json, you can manually set it up in one of the following ways:

Adding the `projectBuildConfig` option directly in the project's `project.json`

In your project's project.json file find the storybook and build-storybook targets. Add the projectBuildConfig property under the options as shown above.

After you add this property, you can run your storybook and build-storybook executors as normal:

nx storybook my-project

and

nx build-storybook my-project

Using the `projectBuildConfig` flag on the executors

The way you would run your storybook and your build-storybook executors would be:

nx storybook my-project --projectBuildConfig=my-project:build-storybook

and

nx build-storybook my-project --projectBuildConfig=my-project:build-storybook

Note: If your project is buildable (eg. any project that has a build target set up in its project.json) you can also do nx storybook my-project --projectBuildConfig=my-project.

In a pure Angular/Storybook setup (not an Nx workspace), the Angular application/project would have an angular.json file. That file would have a property called defaultProject. In an Nx workspace the defaultProject property would be specified in the nx.json file. Previously, Nx would try to resolve the defaultProject of the workspace, and use the build configuration of that project. In most cases, the defaultProject's build configuration would not work for some other project set up with Storybook, since there would most probably be mismatches in paths or other project-specific options.

Configuring styles and preprocessor options

Angular supports including extra entry-point files for styles. Also, in case you use Sass, you can add extra base paths that will be checked for imports. In your project's project.json file you can use the styles and stylePreprocessorOptions properties in your storybook and build-storybook target options, as you would in your Storybook or your Angular configurations. Check out the Angular Workspace Configuration documentation for more information.

    "storybook": {
      "executor": "@nrwl/storybook:storybook",
      "options": {
         ...
        "styles": ["some-styles.css"],
        "stylePreprocessorOptions": {
          "includePaths": ["some-style-paths"]
        }
      },
      ...
    },
    "build-storybook": {
      "executor": "@nrwl/storybook:build",
       ...
      "options": {
         ...
        "styles": ["some-styles.css"],
        "stylePreprocessorOptions": {
          "includePaths": ["some-style-paths"]
        }
      },
     ...
    }

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

plugin-angular.md

plugin-angular.md

Storybook

Setting Up Storybook

Add the Storybook plugin

Using Storybook

Generating Storybook Configuration

Running Storybook

Anatomy of the Storybook setup

Using Addons

Auto-generate Stories

Cypress tests for Stories

Example Files

Setting up `projectBuildConfig`

Adding the `projectBuildConfig` option directly in the project's `project.json`

Using the `projectBuildConfig` flag on the executors

Configuring styles and preprocessor options

More Documentation

Migration Scenarios

Files

plugin-angular.md

Latest commit

History

plugin-angular.md

File metadata and controls

Storybook

Setting Up Storybook

Add the Storybook plugin

Using Storybook

Generating Storybook Configuration

Running Storybook

Anatomy of the Storybook setup

Using Addons

Auto-generate Stories

Cypress tests for Stories

Example Files

Setting up projectBuildConfig

Adding the projectBuildConfig option directly in the project's project.json

Using the projectBuildConfig flag on the executors

Configuring styles and preprocessor options

More Documentation

Migration Scenarios

Setting up `projectBuildConfig`

Adding the `projectBuildConfig` option directly in the project's `project.json`

Using the `projectBuildConfig` flag on the executors