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:
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
- Step 2: Installing Storybook for Angular
- Step 3: Adding the peer dependency
- Step 4: Creating NPM script
- Step 5: Adding Config File
- Step 6: Running the Storybook
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.
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.
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:
defualt-app.component.stories.ts
– This story has the default title property state with value ‘app’.-
custom-app.component.stories.ts
– This story has the custom title property state with value ‘Storybook’.
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.
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!
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.