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 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:
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?
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:
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.
After our first version of the button component is made we can already see our buttons in storybook.
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:
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:
After our implementation our buttons will have some life.
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
After this we have to do some tweaks in our addons.js and config.js (cd ./storybook )
Using actions in Storybook is pretty simple. You just import the action function and use it in your handlers:
Then when clicking on your button you will get an entry in your action logger.
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.
And this is how it looks in storybook:
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:
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:
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.
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.
Then we can wrap our App.js with the ThemeProvider and adjust our storybook configuration so it supports themes.
After this we can make a heading story and it’s implementation to show the theme’s functionality.
And see it in action:
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.