Practical guide to Storybook Driven Development

So a few weeks ago while having a discussion with my team about the approach to developing self-contained React components, I came across this awesome tool: Storybook. To my surprise, I had seen this before, in the example of react-dates.

Storybook is basically a playground for developing your components and their behavior. It also serves as documentation for your component library. You can showcase your components and their different alterations that are linked to props. After playing a bit with storybook and watching this talk on Storybook Driven Development, I decided to make a practical guide on how to get you started.

So as you all know React is a library for making User Interfaces. These last years with libraries like styled-components the interest for making self-contained components ( styling and JSX in one javaScript file) has risen in the React community. React Native started this movement and I always was a fan of it. In this regard, storybook helps us out with the encapsulated design and development of our components.


So what do I need to get started?

So we are gonna start with a clean sheet:

npx create-react-app storybook-driven-development
npm i -g @storybook/cli

Navigate to your project and add the following dependencies:

npm install --save styled-components

Then after that to add storybook to your project you just have to run:

getstorybook

This will automatically add storybook to your project and add the needed dependencies.

To run the storybook instance of your project just run:

npm run storybook

Now you can navigate to http://localhost:9009/ and see your playground with storybook. Easy hey?

Storybook Begins

Writing your first story

So the whole point of Storybook Driven Development is that you actually “sketch” your components first in code before actually coding the implementation. This can be a great start for the development of your components because you can think of the different states you want your component to have before you make the implementation. For example, if you want to make a Button component you can make a default, primary, info, danger and warning component ( Hello Bootstrap 🙃 ). But how does that look?

First of all, you will see a stories folder with an index.js. Here you will find some example code on how to write stories. For our button examples we can begin with this:

First the stories!

Pretty simple right? If we let storybook compile this it will give you an error because you don’t have a Button component. So let’s make one.

First version of button component

After our first version of the button component is made we can already see our buttons in storybook.

Storybook with our buttons

After this, we can start actually coding the state in our components and testing them in storybook. For this, we will use styled-components. We can start by adding the styled-components imports and making our button wrapper. After that, we can start playing with the props that are given to make our different states. Our Button component will look like this:

Button implementation using styled-components

The implementation follows my storybook blueprint, which means I will write my component according to my story. In our stories, we have two props: type and size. We also have the children of the component which in this case will render our button text. On top of our component are our styles. Using styled-components conditionally set some specific styles. For the background color and the width of the button, we used the type and size. We can also define our default props in case you forget to set your props. This can be done with prop types like this:

Prop types and default props in React

After our implementation our buttons will have some life.

Our buttons in Storybook!

Addons

So whats also interesting about storybook is the amount of add-ons that will make your development easier and more predictable. I will highlight a few of these. To get started with these add-ons you have to run:

npm i --save-dev @storybook/addon-actions @storybook/addon-info @storybook/addon-viewport storybook-addon-styled-component-theme @storybook/addon-knobs

After this we have to do some tweaks in our addons.js and config.js (cd ./storybook )

addons.js
config.js

Actions

Using actions in Storybook is pretty simple. You just import the action function and use it in your handlers:

Storybook actions

Then when clicking on your button you will get an entry in your action logger.

Storybook actions addon

withInfo

The withInfo addon provides you with extra information about your component. You can set a description for your component and see the original JSX as well as the props the component supports.

WithInfo addon in action

And this is how it looks in storybook:

WithInfo in action

Knobs

The Knobs addon lets you change props dynamically from the storybook UI. Let’s say for example we want to add a disabled function to our button and we want to also change the color if it’s disabled. In storybook it will look like this:

Knobs addon in action

You use utility functions from the knobs add-on so it knows which type of knobs it will render. In this case, it’s a boolean and it will render a checkbox. We need to then add the change for the disabled color:

Added props.disabled check
Knobs in action

Viewport

Viewport is also a very useful addon because you can test the responsiveness of your components. It provides device viewport simulation just like the one in chrome.

Viewport addon

Bonus: Themes with styled-components

One big feature that styled-components provides is it’s ThemeProvider. The ThemeProvider is a wrapper component for your app that will a theme prop to your components. This will allow you to change your styling based on the theme you have defined. In storybook you can change the themes from the UI.
So let’s change our code so it supports Theming. We can define our themes in a separate JavaScript file:

Theme objects

Then we can wrap our App.js with the ThemeProvider and adjust our storybook configuration so it supports themes.

App.js with styled-component’s ThemeProvider
Storybook config

After this we can make a heading story and it’s implementation to show the theme’s functionality.

Heading component’s story
H1 implementation

And see it in action:

Theming in action

Conclusion

There are many benefits to trying out Storybook and SDD. It will streamline your component design and creation process, it will serve as documentation for onboarding new developers in your team and also help you with applying encapsulated component design. The added bonus of testing your components is also very nice and there are many community add-ons that will make your storybook experience more productive. It can also be used with angular and vue 👌🏼😃.

Thank you for reading! If you like articles like this let me know in the comment section!

PS: All the code for this article can be found on this repo.