Storybook for Angular

Storybook for Angular is a framework that makes it easy to develop and test UI components in isolation for Angular applications. It uses Angular builders and integrates with Compodoc to provide automatic documentation generation.

Install

To install Storybook in an existing Angular project, run this command in your project's root directory:

You can then get started writing stories, running tests and documenting your components. For more control over the installation process, refer to the installation guide.

Requirements

<GetStartedVersions versions={[{ name: 'Angular', range: '≥ 18.0 < 22.0', icon: '/images/logos/renderers/logo-angular.svg' }, { name: 'Webpack', range: '5', icon: '/images/logos/builders/webpack.svg' }]} />

Run Storybook

To run Storybook for a particular project, run the following:

ng run <your-project>:storybook

To build Storybook, run:

ng run <your-project>:build-storybook

You will find the output in the configured outputDir (default is dist/storybook/<your-project>).

Configure

To make the most out of Storybook in your Angular project, you can set up Compodoc integration and Storybook decorators based on your project needs.

Compodoc

You can include JSDoc comments above components, directives, and other parts of your Angular code to include documentation for those elements. Compodoc uses these comments to generate documentation for your application. In Storybook, it is useful to add explanatory comments above @Inputs and @Outputs, since these are the main elements that Storybook displays in its user interface. The @Inputs and @Outputs are elements you can interact with in Storybook, such as controls.

Automatic setup

When installing Storybook via npx storybook@latest init, you can set up Compodoc automatically.

Manual setup

If you have already installed Storybook, you can set up Compodoc manually.

Install the following dependencies:

npm install --save-dev @compodoc/compodoc

Add the following option to your Storybook Builder:

{
  "projects": {
    "your-project": {
      "architect": {
        "storybook": {
          "builder": "@storybook/angular:start-storybook",
          "options": {
            // 👇 Add these
            "compodoc": true,
            "compodocArgs": [
              "-e",
              "json",
              "-d",
              // Where to store the generated documentation. It's usually the root of your Angular project. It's not necessarily the root of your Angular Workspace!
              "."
            ],
          }
        },
        "build-storybook": {
          "builder": "@storybook/angular:build-storybook",
          "options": {
            // 👇 Add these
            "compodoc": true,
            "compodocArgs": [
              "-e",
              "json",
              "-d",
              "."
            ],
          }
        }
      }
    }
  }
}

Go to your .storybook/preview.ts and add the following:

Application-wide providers

If your component relies on application-wide providers, like the ones defined by BrowserAnimationsModule or any other modules that use the forRoot pattern to provide a ModuleWithProviders, you can apply the applicationConfig decorator to all stories for that component. This will provide them with the bootstrapApplication function, used to bootstrap the component in Storybook.

Angular dependencies

If your component has dependencies on other Angular directives and modules, these can be supplied using the moduleMetadata decorator either for all stories of a component or for individual stories.

import { Meta, moduleMetadata, StoryObj } from '@storybook/angular';

import { YourComponent } from './your.component';

const meta: Meta<YourComponent> = {
  component: YourComponent,
  decorators: [
    // Apply metadata to all stories
    moduleMetadata({
      // import necessary ngModules or standalone components
      imports: [...],
      // declare components that are used in the template
      declarations: [...],
      // List of providers that should be available to the root component and all its children.
      providers: [...],
    }),
  ],
};
export default meta;
type Story = StoryObj<YourComponent>;

export const Base: Story = {};

export const WithCustomProvider: Story = {
  decorators: [
    // Apply metadata to a specific story
    moduleMetadata({
      imports: [...],
      declarations: [...],
      providers: [...],
    }),
  ],
};

FAQ

How do I manually install the Angular framework?

The easiest way to install the Angular framework is to run the upgrade command, but you can also set it up manually. First, install the framework:

Then, update your .storybook/main.js|ts to change the framework property:

Finally, update your angular.json to include the Storybook builder:

{
  "projects": {
    "your-project": {
      "architect": {
        "storybook": {
          "builder": "@storybook/angular:start-storybook",
          "options": {
            // The path to the storybook config directory
            "configDir": ".storybook",
            // The build target of your project
            "browserTarget": "your-project:build",
            // The port you want to start Storybook on
            "port": 6006
            // More options available, documented here:
            // https://github.com/storybookjs/storybook/tree/next/code/frameworks/angular/src/builders/start-storybook/schema.json
          }
        },
        "build-storybook": {
          "builder": "@storybook/angular:build-storybook",
          "options": {
            "configDir": ".storybook",
            "browserTarget": "your-project:build",
            "outputDir": "dist/storybook/your-project"
            // More options available, documented here:
            // https://github.com/storybookjs/storybook/tree/next/code/frameworks/angular/src/builders/build-storybook/schema.json
          }
        }
      }
    }
  }
}

How do I migrate to an Angular Storybook builder?

The Storybook Angular builder is a way to run Storybook in an Angular workspace. It is a drop-in replacement for running storybook dev and storybook build directly.

You can run npx storybook@latest automigrate to let Storybook detect and automatically fix your configuration. Otherwise, you can follow the next steps to adjust your configuration manually.

With a single project in your Angular workspace

Go to your angular.json and add storybook and build-storybook entries in your project's architect section, as shown above.

Then, adjust your package.json script section, to replace the existing Storybook scripts with the Angular CLI commands:

{
  "scripts": {
-    "storybook": "start-storybook -p 6006", // or `storybook dev -p 6006`
-    "build-storybook": "build-storybook" // or `storybook build`
+    "storybook": "ng run <project-name:storybook",
+    "storybook": "ng run <project-name:storybook",
  }
}

Note that compodoc is now built into @storybook/angular; you don't have to call it explicitly. If you were running compodoc in your package.json scripts, you can remove the related script:

{
  "scripts": {
-    "docs:json": "compodoc -p tsconfig.json -e json -d ./documentation",
-    "storybook": "npm run docs:json && start-storybook -p 6006",
-    "build-storybook": "npm run docs:json && build-storybook"
+    "storybook": "ng run <project-name:storybook",
+    "storybook": "ng run <project-name:storybook",
  }
}

With multiple projects in your Angular workspace

In case you have multiple projects, you will have to adjust your angular.json and package.json as described above for each project you want to use Storybook with. Please note that each project should have a dedicated .storybook folder placed at the project's root directory.

You can run npx storybook@latest init sequentially for each project to set up Storybook for each of them to automatically create the .storybook folder and create the necessary configuration in your angular.json.

You can then combine multiple Storybooks with Storybook composition.

How do I configure Angular's builder for Storybook?

These are common options you may need for the Angular builder:

The full list of options can be found in the Angular builder schemas:

• Build Storybook
• Start Storybook

API

Options

You can pass an options object for additional configuration if needed:

The available options are:

builder

Type: Record<string, any>

Configure options for the framework's builder. For this framework, available options can be found in the Webpack builder docs.