Storybook for Angular | Storybook docs (original) (raw)

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 ≥ 18.0 < 20.0
• Webpack ≥ 5.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:

angular.json

Run Storybook

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

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

Add the following option to your Storybook Builder:

angular.json

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

.storybook/preview.ts

applicationConfig decorator

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.

ChipsModule.stories.ts

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.

YourComponent.stories.ts

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

Do you have only one Angular project in your workspace?

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

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

package.json

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.

package.json

Also, compodoc is now built into @storybook/angular; you don't have to call it explicitly. If we're running compodoc in your package.json scripts like this:

package.json

Change it to:

package.json

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 you want to use Storybook. Please note that each project should have a dedicated .storybook folder placed at the project's root.

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:

.storybook/main.ts

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.