Angular and Storybook

Implementing Storybook in an Angular multi-application project

5 min readAug 11, 2020

Hi everyone, in this article we will have a look at how to implement Storybook in an existing Angular multi-application project. The motivation behind this is the difficulty I had when implementing Storybook in a real Angular project, a 3 years old multi-application project that has been tooled and migrated from previous versions, creating a miss-match of Node packages versions that, even without causing a problem during installation, generated a number bugs when running Storybook, bugs that were not present in projects recently created by Angular CLI. So let’s roll.

Introduction

As an application grows in size and complexity its documentation starts to get sparsed, becoming harder to maintain as implementations differ from the application pather. This happens even if we don’t add the change in the stack, different versions, improvements, or changes in the development staff. It’s hard to prevent deviations from the applications pather without good documentation, this being a problem every company I worked in the past has faced.

When working with Angular projects, like multi-application ones, it’s common to see the creation of a library application, not an angular lib project, but an application that holds all components documentation and a style guide. There are other ways to achieve this, like using a third party style guide. In this category we have some popular solutions like Docz and Styleguidis, but these two have none or limited integration with Angular. Another popular solution is Storybook, and one of the good aspects of Storybook is that it reads angular projects, so it integrates nicely with the angular architecture.

If you want a quick tutorial there are two places to start, the Storybook Angular tutorial for a simple integration step by step, or in NX Storybook overview to see how to add Storybook to an existing project structure using NX. We are not going to abord this two tutorials here, just a small portion of the Storybook tutotial. This is because there were problems when NX was used in an existing project, so we are going to integrate Storybook line by line, file by file.

So we have our pick, let us implement together Storybook in an Angular multi-application project.

Adding Storybook:

First step, let us install the dependencies:

npm install @storybook/angular --save-dev
npm install babel-loader @babel/core --save-dev

Now, we need to write Storybook main file, the main.js. In this file we will declare where Storybook should look for the stories, normally looking for .stories.[jt]s files, the [jt] syntax means it will look for both js and ts files. Storybook, by default, will look for the main.js in a folder at the root of your project called .storybook , just like this:

And the main file is declared like this:

We are almost finished setting up .storybook folder, missing only the typescript configuration file. The typescript configuration file is a JSON file called tsconfig.json , it bears a lot of configuration options for the typescript compiler, but we only are going to focus on three, includes, exclude, extends. Includes will select any files in the paths provided, excludes creates exceptions in those paths, like telling the compiler to skip test files, and extends target the main typescript configuration getting any already defined compiler options. The tsconfig.json should be like this:

Add this to your package.json scripts:

"storybook": "start-storybook"

And we are done, now let’s create ower first stories.

Creating stories

In this section we will be following the Storybook quick tutorial, as we create two stories.

Now, create a file in your project named index.stories.ts and add the following code to the file:

Storybook quick start tutorial (Storybook for Angular, 2020)

With these two stories implemented we can now run Storybook with the command:

npm run storybook

Storybook should open something like this in your browser:

There it is, Storybook running.

Addons

Now, addons are like upgrades to your Storybook, they add new functionalities and workflows, in the Storybook addons page you can check a number of addons created by the community and by Storybook core maintainers team.

Addons are easy to use, they just need to be installed in your node package and included in the addons array in the main.js file, like this:

And after that just follow that addons own tutorial and documentation to use it.

Storybook and angular.json

We can’t speak about using Storybook in an Angular project without glossing over how the two interact.

Storybook reads Angulars project file, theangular.json file, which means it will load every configuration prop in that file. We can just create a project with the name storybook and all configuration declared there will be loaded, if not, Storybook will look for the default project or the one was created first. The advantages of this integration are quite obvious, our assets and styles, like bootstrap, are automatically loaded into the Storybook application to be used by our stories.

Bugs

One of the reasons I decided to write this article was the number of problems encountered during Storybook implementation. The three main problems were bugs during installation, that prevented Storybook from running and that affected Angular application build process.

The first was present when using NX to add Storybook to Angular, and was being caused, by what I could getter, by a mismatch in the @storybook/schematics with other packages. As I was unable to find a match so the NX implementation was abandoned.

Now, about the second problem. When starting Storybook it would not recognize the module from Storybook tutorial, the @storybook/angular/demo, and you would receive an error message like the one below.

The way around this bug is to create a type file in .storybook folder, the file would be called typings.d.ts , and would contain the following:

We also need to add this file to Storybook tsconfig.json file, in the files array, like this:

And the last problem I encountered was when building an application that has a Storybook file in its structure. During the build process compilation would fail when trying to read Storybook types and definitions, like the image below.

Error building application (Author, 2020)

To solve this one you only need to exclude any Storybook file, the ones with the .stories.ts , from the compilation, and to do this we will add this restriction to the exclude array in the application typescript configuration file, the tsconfig.app.json file, like the example below.

Wrapping up

With seeming integration possibility, addons support giving it comprehensive customization and with the community support, Storybook may become a compulsory choice to an Angular multi-application project.