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!
Storybook for Angular is only supported in Angular projects.
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:
Configuration element | Description |
---|---|
"browserTarget" | Build target to be served using the following format. "example-project:builder:config" |
"tsConfig" | Location of the TypeScript configuration file, relative to the current workspace. "tsConfig": "./tsconfig.json" . |
"port" | Port used by Storybook. "port": 6006 |
"host" | Set up a custom host for Storybook. "host": "http://my-custom-host" |
"configDir" | Storybook configuration directory location. "configDir": ".storybook" |
"https" | Starts Storybook with HTTPS enabled. "https": true Requires custom certificate information. |
"sslCa" | Provides an SSL certificate authority. "sslCa": "your-custom-certificate-authority" Optional usage with "https" |
"sslCert" | Provides an SSL certificate. "sslCert": "your-custom-certificate" Required for https |
"sslKey" | Provides an SSL key to serve Storybook. "sslKey": "your-ssl-key" |
"smokeTest" | Exit Storybook after successful start. "smokeTest": true |
"ci" | Starts Storybook in CI mode (skips interactive prompts and will not open browser window). "ci": true |
"quiet" | Filters Storybook verbose build output. "quiet": true |
"docs" | Starts Storybook in documentation mode. "docs": true |
"styles" | Provide the location of the application's styles to be used with Storybook. "styles": ["src/styles.css", "src/styles.scss"] |
"stylePreprocessorOptions" | Provides further customization for style preprocessors resolved to the workspace root. "stylePreprocessorOptions": { "includePaths": ["src/styles"] } |
The full list of options can be found in the Angular builder schemas:
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.