Set up Storybook for Angular Projects

This guide will walk you through setting up Storybook for Angular projects in your Nx workspace.

Set up Storybook in your workspace

You 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 an Angular project

You can generate Storybook configuration for an individual Angular project by using the @nx/angular:storybook-configuration generator, like this:

❯

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

Auto-generate Stories

The @nx/angular:storybook-configuration generator has the option to automatically generate *.stories.ts 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.ts 3└── my.component.stories.ts 4

If 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/angular:stories generator:

❯

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

Example

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/angular: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.component.ts 11| | | | | | ├── my-button.component.stories.ts 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... 23

Example Files

Let's take for example a library in your workspace, under libs/feature/ui, called feature-ui with a component, called my-button.

Let's say that the template for that component looks like this:

libs/feature/ui/src/lib/my-button/my-button.component.html
1<button [disabled]="disabled" [ngStyle]="{ 'padding.px': padding }"> 2 {{ text }} 3</button> 4

and the component looks like this:

libs/feature/ui/src/lib/my-button/my-button.component.ts
1import { Component, Input } from '@angular/core'; 2 3@Component({ 4 selector: 'feature-ui-my-button', 5 standalone: true, 6 templateUrl: './my-button.component.html', 7 styleUrls: ['./my-button.component.css'], 8}) 9export class MyButtonComponent { 10 @Input() text = 'Click me!'; 11 @Input() padding = 10; 12 @Input() disabled = true; 13} 14

Story file

The @nx/angular:storybook-configuration generator would generate a Story file that looks like this:

libs/feature/ui/src/lib/my-button/my-button.component.stories.ts
1import type { Meta, StoryObj } from '@storybook/angular'; 2import { MyButtonComponent } from './my-button.component'; 3import { within } from '@storybook/testing-library'; 4import { expect } from '@storybook/jest'; 5 6const meta: Meta<MyButtonComponent> = { 7 component: MyButtonComponent, 8 title: 'MyButtonComponent', 9}; 10export default meta; 11type Story = StoryObj<MyButtonComponent>; 12 13export const Primary: Story = { 14 args: { 15 text: 'Click me!', 16 padding: 10, 17 disabled: true, 18 }, 19}; 20 21export const Heading: Story = { 22 args: { 23 text: 'Click me!', 24 padding: 10, 25 disabled: true, 26 }, 27 play: async ({ canvasElement }) => { 28 const canvas = within(canvasElement); 29 expect(canvas.getByText(/my-button works!/gi)).toBeTruthy(); 30 }, 31}; 32

Notice the interaction test on the second story, inside the play function. This just tests if the default text that appears on generated components exists in the rendered component. You can edit this test to suit your needs. You can read more about interaction tests here.

Understanding the role of browserTarget

You will notice that browserTarget is specified for the storybook and build-storybook targets, much like it is done for serve or other targets. Angular needs the browserTarget for Storybook in order to know which configuration to use for the build. If your project is buildable (it has a build target, and uses the main Angular builder - @angular-devkit/build-angular:browser, @angular-devkit/build-angular:application or @angular-devkit/build-angular:browser-esbuild) the browserTarget for Storybook will use the build target, if it's not buildable (or is using another Angular builder) it will use the build-storybook target. You do not have to do anything manually. Nx will create the configuration for you. Even if you are migrating from an older version of Nx, Nx will make sure to change your package.json Storybook targets to match the new schema.

You can read more about the browserTarget in the official Angular documentation.

Your Storybook targets in your project.json (or if you run nx show project my-project --web) will look like this:

project.json
1 "storybook": { 2 "executor": "@storybook/angular:start-storybook", 3 "options": { 4 ... 5 "browserTarget": "my-project:build" 6 }, 7 ... 8 }, 9 "build-storybook": { 10 "executor": "@storybook/angular:build-storybook", 11 ... 12 "options": { 13 ... 14 "browserTarget": "my-project:build" 15 }, 16 ... 17 } 18

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

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

Older migration scenarios

Recipes