Storybook for Angular – Beginner’s Quick Guide

Remember the days when Notepad used to be our development environment and every change in Background and Font had to be checked by opening the HTML page in our browser? That too, assuming that all the attributes in all the tags were correct and every container tag was closed. Now we are in a time where Storybook is a real phenomenon.

Storybook provides a development environment that practically shows your resultant UI as you’re writing the code. Exciting much? With help of Storybook, you can interactively develop your UI components while visualizing their every state. Additionally, Storybook allows the developer to work on the UI components in complete isolation so that you can actually do the development outside the app. This enables the developer to work on specific UI Components without caring about the app’s dependencies and requirements.

To get started, you should be having at least npm v5.2.0 installed as we will be using npx command.

Setting up Storybook for Angular

Storybook can be set up in two ways:

  1. Installing Storybook with CLI
  2. Installing Storybook manually

Installing Storybook for Angular with CLI

Storybook has its own CLI (Command Line Interface) which make it easy to use as all the required specific configuration and dependencies are being handled itself. So, this is the easiest and fastest way to get started with Storybook. 

Below are the steps to install Storybook with CLI:

Step 1: Creating an Angular Project

An Angular Project can be created easily by using the @angular/cli build tool. Here is the code for the same.

npx @angular/cli new <your_app_name>
cd <your_app_name>

Step 2: Install the Storybook CLI

Run below command to install the Storybook CLI and the required Storybook.

npx @storybook/cli getstorybook

Storybook CLI will detect the project type – Angular, React, or Vue etc and will installed the respective Storybook along with it’s dependencies.

Installing Storybook manually

Here are the steps for manually setting up Storybook for Angular:

Step 1: Creating an Angular Project

An Angular Project can be created easily by using the @angular/cli build tool. Here is the code for the same.

npx @angular/cli new <your_app_name>
cd <your_app_name>

Step 2: Installing Storybook for Angular

Install the @storybook/angular as devDependencies with the below code.

npm install @storybook/angular --save-dev

Step 3: Adding the peer dependency

Install peer dependency babel-core  as below.

npm install babel-core --save-dev

Step 4: Creating NPM Scripts

Here we need to add the below code to the package.json file.  We are defining the script which will be invoking later in step 6 with npm run storybook at the command line.  The option -p specify the port number where the dev server will listen to and the config file will be read from .storybook directory by default. To change .storybook directory use  -c option to specify from which directory the config file should be read. 

{
  "scripts": {
    "storybook": "start-storybook -p 9001 -c .storybook",

  }
}

Step 5: Adding Config File

Create .storybook folder defined in the above NPM scripts as below screenshot. 

storybook config folder structure

Create config.js file under the newly created .storybook folder and add the below snippet to it. The snippet will search the ../src/stories folder and its subfolder  for file name ending with .stories.ts and those will be loaded to the Storybook.

import { configure } from '@storybook/angular';

// automatically import all files ending in *.stories.ts
const req = require.context('../src/stories', true, /.stories.ts$/);
function loadStories() {
  req.keys().forEach(filename => req(filename));
}

configure(loadStories, module);

Step 6: Running the Storybook

Start Storybook with below npm command .  If you received error while trying to start the Storybook, try changing the port number in the npm script (refer step 6)  and see if it works.

npm run storybook

Navigate to http://localhost:9001 to see the Storybook in action as below. You won’t see any story as it has not been created yet at this point.

storybook for angular without stories

Writing Stories 

We’re ready to write the Angular Stories under src/stories . Let’s write a simple stories for the Angular CLI created AppComponent which has title property with the default value ‘app’ assigned. We will be creating below two files under stories folder as shown below screenshot:

  1. defualt-app.component.stories.ts – This story has the default title property state with value ‘app’.
  2.  custom-app.component.stories.ts – This story has the custom title property state with value ‘Storybook’.

storybook for angular stories folder structure

Add below snippet to the newly createdcustom-app.component.stories.ts file. In line no 7, we are overriding the title property with ‘Storybook’.

import { storiesOf } from '@storybook/angular';
import { AppComponent } from '../app/app.component';

storiesOf('App Component', module).add('Custom title property', () => ({
  component: AppComponent,
  props: {
    title: 'Storybook'
  },
}));

and, add below snippet to defualt-app.component.stories.ts file. Here, we are not setting the property overrides. So,  the title property will have the default value assigned in the src/app/app.component.ts file.

import { storiesOf } from '@storybook/angular';
import { AppComponent } from '../app/app.component';

storiesOf('App Component', module).add('Default title property', () => ({
  component: AppComponent,
  props: { },
}));

You will be able to see the changes like below screenshots without the need for the Storybook to reload as Storybook leverages Webpack’s HMR (Hot Module Replacement) API which provides instant updates of any changes to stories or modification to the Angular components without the need for the page reload.

storybook for angular stories with stories

On the left side, you will find  component explorer with its available state under it. So, the story we created will be displayed under the App Component with its state – Custom title property and Default title property. Clicking the Default title property will display the Heading as – Welcome to app! and clicking the Custom title property will change to -Welcome to Storybook!

storybook for angular in action animation

This is how Storybook can be configured and run for Angular.

Conclusion

As the new technologies and programming languages are developing at such a great pace, the development environments also need to cope up. Storybook is a great example of a development platform that can easily adapt the contemporary UI developing languages/frameworks/libraries. It is easy for developers to monitor the states of their UI components and without employing 2-3 different tools at one time. Storybook is the perfect platform a UI developer can ask for.

Mapu

I am a technology freak with passion for UI technology.

Leave a Reply