Installing and exploring Storybook
Let's learn about the installation process of Storybook.
Starting from the beginning#
In this course, we will use Storybook in a real-world app. However, to learn the basics of Storybook and not get distracted with other things, let's start with a fresh project and later move to a more complete project.
We will be using Create React App CLI to generate the base project for us. So, open your terminal, choose the folder where you'd like to place your project, and run the following command:
Important: We pin
create-react-appversion to 5 to make sure the installation will be in line with the contents of this course.
By running this command, you should now have a Typescript React project! Let's add Storybook to it.
Installing Storybook in any project is a rather simple process, given that Storybook has a CLI that does all the work for us. By running a single command in the root folder of your project:
The CLI will figure out what type of project you have (React/Vue/etc.) and install all the necessary libraries for that project, including an initial boilerplate that teaches us how to use it in its basic form.
As you can see, Storybook's CLI took care of everything for us. Storybook added a couple scripts to
storybook will start Storybook in development mode.
build-storybook will build storybook as an application and provide you with a folder of statics that you can publish in any hosting platform you'd like, therefore making your Storybook available for everyone to see! We'll be covering about publishing Storybooks later in the course.
We should be able to run Storybook with the following command:
A new tab in your browser should open with your Storybook running:
Storybook configuration and structure#
When looking at our Storybook, we see that there's an Introduction page with helpful links and tutorials alongside an example of a Button, an atomic component, the Header, which is a composition of components, and a Signup Page, a page using all the previous components. Those are there to serve as examples for us to create our own stories.
But wait, what do you mean by stories?#
Components normally have different UI states based on the properties they receive, or interactions which happen to them. When looking at Button example in Storybook, we see that it has states like Primary, Secondary, Large and Small. Storybook has the concept of stories, where each story renders a component with certain annotation to it (like the props to make the Button in a Primary state!).
In order to write stories, you create a file alongside your component (e.g.
Button.stories.tsx) where you import your component and write one story for each UI state you'd like to document. Don't worry about it for now; we will go into detail in the next lesson.
As you can see, all
stories were generated under a folder called stories.
There are a few ways to organize files, and it is up to you and your team to find which way is most suitable for you. Here are two examples that you could use:
Example One - stories folder:#
Storybook adds files this way to make it simpler to remove and not affect your existing folders. Even though some teams like to use this structure, I prefer the next one.
Example Two - colocated files:#
I prefer having the stories colocated in the same folder as the component they relate to (example two). This makes it easier to find them when working on the said components. Here's a very nice article from Kent C. Dodds showing the values of colocation. This applies to tests, stories, styles, etc.
Storybook also added a folder called
.storybook. This folder is the home of any configuration file that Storybook might use. Let's check them, and at the same time introduce concepts that we will be using later to do things like adding global styles to Storybook, installing addons, etc.
Storybook has a server and a client. The
main.js file configures the server.
main.js relates to how Storybook loads and processes the story files (Remember this). It contains the main configuration that Storybook needs to work.
This is where you define the path and extension of your story files and the storybook addons you want to use, and you can add custom Webpack/Babel configuration if you need. As
main.js configures the server, in order for your changes in that file to have effect, it is required to stop Storybook's process in your terminal and restart it again with
main.js tells Storybook how to load and process stories? Well,
preview.js tells Storybook how to render stories. Such configurations are related to the client. If you have a global configuration that you want to apply in every story, such as CSS imports or a mock configuration, this file is the place to put them. This file is also the place to set global decorators, parameters, and globalTypes, which we will be talking about in later lessons. In
preview.js, file changes take effect immediately, so there's no need to restart Storybook when you make them.
If you're looking for more information on configuring stories, you can find it in the documentation.
In the next lesson, we will go through the basics of Storybook and write our first story!