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 includes:

• 🧱 Uses Angular builders
• 🎛️ Compodoc integration
• 💫 and more!

Requirements

• Angular ≥ 15.0 < 18.0
• Webpack ≥ 5.0
• Storybook ≥ 8.0

Getting started

In a project without Storybook

Follow the prompts after running this command in your Angular project's root directory:

More on getting started with Storybook.

In a project with Storybook

This framework is designed to work with Storybook 7+. If you’re not already using v7, upgrade with this command:

Automatic migration

When running the upgrade command above, you should get a prompt asking you to migrate to @storybook/angular, which should handle everything for you. In case that auto-migration does not work for your project, refer to the manual migration below.

Manual migration

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:

Run Storybook

To run Storybook for a particular project, please run:

To build Storybook, run:

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

Setup 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 the elements that you can interact with in Storybook, such as controls.

Automatic setup

When installing Storybook via npx storybook@latest init, you will be given the option to set up Compodoc automatically.

Manual setup

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

Install the following dependencies:

Add the following option to your Storybook Builder:

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

applicationConfig decorator

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

moduleMetadata decorator

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.

FAQ

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 try let Storybook detect and automatically fix your configuration. Otherwise, you can follow the next steps to manually adjust your configuration.

Do you have only one Angular project in your workspace?

First, go to your angular.json and add storybook and build-storybook entries in architect section of your project like shown above.

Second, adjust your package.json script section. Usually, it will look like this:

Now, you can run Storybook with ng run <your-project>:storybook and build it with ng run <your-project>:build-storybook. Adjust the scripts in your package.json accordingly.

Also compodoc is now built-in in @storybook/angular and you don't have to call it explicitly. If were running compodoc in your package.json scripts like this:

Change it to:

I have multiple projects in my Angular workspace

In this case you have to adjust your angular.json and package.json as described above for each project in which you want to use Storybook. Please note, that each project should have a dedicated .storybook folder, which should be placed in the root of the project.

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

You can then use Storybook composition to composite multiple Storybooks into one.

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 Angular, , available options can be found in the Webpack builder docs.