A Storybook with Angular

Bridging the gap between design and development is always a constant struggle when we are talking about creating web or mobile applications.

Teams are always trying to implement different approaches to solve this problem and usually the main part of the solution is an interactive style guide/design system built with HTML, CSS, and JavaScript. A good example of this can be found in the Lightning Design System built by Salesforce.

Lightning Design System by Salesforce

Although this approach might be better than referencing any non-interactive documents and has some advantages as it’s framework agnostic, easy to run and allows faster prototyping, it has some flaws.

Any component you build in Angular (or any other framework) probably won’t be compatible with this solution which will require you to build the same components more than once in different ways. One that can be included in your Angular application and another that can be used in your style guide. This, of course, causes issues with inconsistency, ownership problems and makes it difficult to maintain.

Imagine that we can just include already built Angular components and create an interactive style guide out-of-the-box. And what if I said it can also be used for testing!

Storybook is a development environment for UI components. It allows us to browse our component library in an isolated environment, view different states of each component, but also to interactively develop, design and test components. And the most important thing is that it works with Angular.

For the purpose of this post, I built a demo application in Angular that represents a simple task management board. It uses Angular Material Drag and Drop to move around tasks from one column to another, but also to add new ones. Code for the project is available on GitHub.

Task management board app built in Angular

Just by looking at this example you can notice that it makes sense to create two components. One that will represent a Task and another that represents a TaskList (column). It would be interesting to see how these components look in an isolated environment, to be able to test their behavior in different scenarios with different data used as input. Let’s see what Storybook has to offer.

Storybook for the Angular Task management board app

Here we have created two stories: one for the Task component and another for the TaskList component. We can see how Tasks look like without any labels, names or dates, how TaskList looks when it’s empty or how it handles dragging each individual Task component. This approach allows both designers and developers to work on the same codebase and collaborate together to improve already built solutions, but also to test all use-cases of the components.

Ok, demos are fine, but let’s see how to integrate Storybook to our project. Assuming you already have you Angular app setup, all we have to do is install the Storybook and needed dependencies from npm and we are ready to go.

npm i — save-dev @storybook/angular @babel/core babel-loader

Next step would be to configure the Storybook, and that’s done with creating a folder named “.storybook” in the root directory of your project and adding a “config.js” file there. The configuration file will basically list all your stories so the Storybook knows where to find them.

As we have two types of components here, we will write two stories with different scenarios in each of them. Here we will show how to create a story for the Task component.

We covered how our component looks without any passed data but also with just parts of the possible properties. Very simple and easy, and using already created components.

Now, all we have to do is run Storybook and see how this works. To be able to do this we will add this line in the scripts part of our package.json file.

“storybook”: “start-storybook -p 9001 -c .storybook”

Running a simple command:

npm run storybook

will start the localhost server and allow us to run Storybook on top of our already built Angular project.

Now we can test and play with our component in an isolated environment. Test what happens in different scenarios and make sure our components won’t break. But also to enable our design team to work on components that are used in the application. This means that changes in the style files (css/scss/less) of the component will be reflected both in the Storybook and in the application itself.

There is no code duplication, no issues with inconsistency or ownership problems.

Advantages of this approach are obvious:

  1. Integrates with Angular
  2. Immediate feedback on changes
  3. Change history through code versioning
  4. Manual tests are easier
  5. Snapshot testing
  6. Component isolation

So there you have it! We’ve seen why you should think about using Storybook and how easy it is to set it up to work with Angular. I won’t try to convince you that it will solve all your problems, but it might help with some common issues both developers and designers are struggling with.

Good luck and let me know if you have any questions!