So how can we use Storybook to build libraries and design systems that self-document as we build them?

• What is Storybook?
• What are we going to build?
• Step 0: Bootstrapping an app
• Step 1: Installing Storybook
• Step 2: Creating a new button
• Step 3: Using our new Button component
• Repeat: Creating a new Header component
• More Storybook features

What is Storybook?

Storybook is a JavaScript tool that allows developers to create organized UI systems making both the building process and documentation more efficient and easier to use.

Lonely Planet's Backpack UI

Once you build out a component, Storybook lets you create a "story" file where you can then import your component and create various use case examples in an iFramed sandbox using that component.

This provides an organized and focused environment to build new components and work on existing ones.

What are we going to build?

We're going to bootstrap a new React JS app using Create React App.

Inside that app, we're going to install Storybook and create a few new components that will help us learn how to create new components that we can work on in a story and then use it in a React app.

Step 0: Bootstrapping an app

To get started, we're going to start from scratch with Create React App. This will help us focus on getting productive in Storybook rather than walking through integrating it into a current app.

That said, if you're already working with an app created using Create React App that's not ejected, you should be able to still follow on with Part 1 and beyond just the same!

So let's get started by navigating to where we want to create our new app and run the Create React App command:

npx create-react-app my-storybook

Note: feel free to replace my-storybook with the directory name of your choice.

Bootstrapping with Create React App

Once that's finished running, you can navigate to the directory:

cd my-storybook

And we're ready to go!

Step 1: Installing Storybook

Storybook luckily makes it really easy to get started with a standard installation of React. Particularly with Create React App, Storybook automatically detects that we're using an app created using CRA and installs the dependencies and scaffolds everything for us.

Initializing Storybook

To get started installing Storybook, run:

npx -p @storybook/cli sb init

Initializing Storybook in a React app

If you aren't using Create React App or it didn't work, you can check out their available guides in their docs.

After that's finished, all of our Storybook dependencies should be installed.

Finished installing Storybook

Starting up Storybook

So now we're ready to get moving! Finally, run:

yarn storybook
# or
npm run storybook

And once everything finishes loading, Storybook will open a new tab in your browser and you should now see a welcome message inside of your new Storybook dashboard!

Storybook welcome page

Follow along with the commit!

Step 2: Creating a new button

If you took a second to poke around the dashboard, you might have noticed that it comes pre-loaded with a Button that's available as a demo.

Storybook demo button

You should also notice if you click the button, you actually see an action print out inside of the Actions tab at the bottom. This shows the event that's captured from the button click.

It's simple, but this is great to get a nice feel about what to expect in storybook. The only issue is, this is meant purely for demonstration purposes, so let's build our own button to replace it.

Creating a new Button component

To get started, let's first create a few directories:

• Under src, create a new folder called components
• Under components, create a new folder called Button

Once you create those folders, create a new file called index.js inside of your src/components/Button folder and inside add:

// Inside src/components/Button/index.js

export { default } from './Button';

This will import the next file we created called Button.js which will allow us to more easily import our files with src/components/Button instead of /src/components/Button/Button.

Next, let's create Button.js right next to our index.js file with the following content:

// Inside src/components/Button/Button.js

import React from 'react';

const Button = ({ children, ...rest }) => {
  return (
    <button className="button" {...rest}>
      { children }
    </button>
  )
}

export default Button;

Here, we're creating a new component called Button that adds a class of button to the element and passes through the children. We're a additionally destructuring the rest of the props into the rest variable and spreading that value into the <button> element.

If you've followed along, your files should now look like this:

Button component in React

Using our new Button component

So now that we have our Button component, let's use it!

Open up the file src/stories/1-Button.stories.js and replace the line that's importing Button with:

Updating the Button Storybook story

And once you hit save, you can open back up your browser tab with your Storybook dashboard, and you can now see a button that looks mostly similar, but it uses the browser's default styles for the <button> element. You'll even notice that if you click it, the event will still be logged under the Actions tab.

Styling our Button component

Finally, we probably don't want to use the browser default styles, so let's make it look nice.

In our src/components/Button directory, add a new file Button.css and add the following content:

/* Inside src/components/Button/Button.css */

.button {
  color: white;
  font-weight: bold;
  background-color: blueviolet;
  border: none;
  padding: .8em 1em;
  border-radius: .2rem;
}

This applies a few styles to our .button class like adding a background color and changing the font color to white.

But if you open Storybook, you'll notice it didn't do anything. To use it, we need to import it into our component.

Inside src/components/Button/Button.js add the following at the top under the React import:

import './Button.css';

And once you save that and open up your browser, you should now see our new button with our updated styles!

New Button in Storybook

Follow along with the commit!

Step 3: Using our new Button component

The ultimate goal of our component is to use it right? So let's add it to our app.

Switching over to the React app

First we'll need to either start our React app in a new terminal tab or kill the Storybook process and start the React process there. To start the React app using Create React App, run:

yarn start
# or
npm run start

Once that loads, we should have our standard Create React App if you're following along with me:

New Create React App

Importing and using the new button

Next, inside of src/App.js, let's import our new Button at the top of the page:

import Button from './components/Button';

With Button imported, we can use it. Here, we can simply add it anywhere we want in the page. I'm going to replace the Learn React link with:

<p>
  <Button>Hello, Storybook!</Button>
</p>

And if we save and reload the page, we should now see our Button on the page!

New Button in Create React App

Follow along with the commit

Repeat: Creating a new Header component

The great thing about Storybook and React (or any of the supported frameworks) is that this process scales to as many components as you want.

So let's build another component!

Creating our Header component

Similar to our Button, let's start off by creating the set of directories and files that give us our component.

Since we already did this once, I'm going to provide the code without walking through what's going on.

Let's start off by spinning back up our Storybook server with:

yarn storybook
# or 
npm run storybook

Create a Header directory inside the src/components directory.

Create an index.js file inside of src/components/Header with the following content:

// In src/components/Header/index.js

export { default } from './Header';

Create a Header.js file inside of src/components/Header with the following content:

// In src/components/Header/Header.js

import React from 'react';
import './Header.css';

const Header = ({ children }) => {
  return (
    <h2 className="header">
      { children }
    </h2>
  )
}

export default Header;

Create a Header.css file inside of src/components/Header with the following content:

/* In src/components/Header/Header.css */

.header {
  font-family: sans-serif;
  font-size: 2.5em;
  color: blueviolet;
  border-bottom: solid 5px aqua;
  padding-bottom: .2em;
  box-shadow: 0 5px 0 blueviolet;
}

Now if you notice, if you try to open up Storybook, again, nothing will happen. This time we need to create a new story file.

Creating a new Story file

Inside src/stories, add a new file called 2-Header.stories.js:

// Inside src/stories/2-Header.stories.js

import React from 'react';

import Header from '../components/Header';

export default {
  title: 'Header',
  component: Header,
};

export const Text = () => <Header>Hello Header</Header>;

Here's a breakdown of our story file:

• First, we import our component – this is pretty standard any time we want to use it
• The first thing we export is a default object. With Storybook, it expects the default export to be the configuration of our story, so here we provide it with a title and we pass in the component that we're using for this story
• The second and last thing we export is the Text constant. With Storybook, any non-default export will be considered a variation that will get nested under the title that you provide in the default export

And if you save this file and open up your Storybook dashboard in the browser, you should now see the new header!

New Header component in Storybook

Using the Header component

Using our component is just the same as our Button component, so inside of src/App.js, let's add our Header.

After starting your React server, first import our new Header:

// In src/App.js

import Header from './components/Header';

Then add it to the top of the page:

// In src/App.js

<Header>My App</Header>

And if you open the page, we'll see our new Header!

Create React App with new Header and Button components

Follow along with the commit!

Adding more components

As you've noticed with our second Repeat step – adding a new component is pretty much the same process for any type of component we want to add. Once we have it in our library, we can develop it in a focused environment and then import it to our app to use.

You can now use this to manage your library of components and better maintain an entire system for your project!

More Storybook features

Storybook doesn't stop with just adding components, it provides the ability to configure Addons that enhance the core capabilities opening up a lot of possibilities.

Here are some of my favorites...

Story Source

When building a component system, the hope is that people can easily use these components. But if you don't have documentation, someone would have to open up the file or try to find another use example.

Instead, Story Source shows the code source of the story file you created allowing someone browsing your Storybook dashboard to get an example right along with the component output!

Storybook Story Source demo

Storyshots

If you're a fan of automated testing, you might have heard of using Jest or another tool for adding snapshot testing to your app.

StoryShots is a way to easily add Jest snapshot testing to your component system. It creates snapshots based off of the stories you create so you can make sure that your components aren't fundamentally changing (or breaking) during development.

Snapshot example with StoryShots

What's your favorite part of Storybook?

Share with me on Twitter!

Continue the conversation!

When I started to write this post, I had finished my first serious week of contributing to open source. I mainly contributed to the project Storybook. This post will describe the contributions and interactions that took place this week. It will also focus on the path that led up to this week.

I want to talk about the change in mindset and motivation that (finally) got me started. I will show you what I did to get to my first contribution, and I will share what I learned from this week and my experience of everything as a whole.

While I’m aware that one week has not made me an open source expert, the stories I describe will be from my own subjective perspective. Developers trying to get into open source, like me before this week, might find some value in reading the story of someone in very similar shoes.

In this post, I won’t go over the basics about getting into open source. I will not cover how to choose a project to contribute to. Nor will I cover why, how, and what you should contribute to the project. Open Source Guides covers all these topics very well. You should definitely check it out if you’re looking for advice regarding those topics.

_“A highway down a countryside with a red wheat field” by [Unsplash](https://unsplash.com/@alice_hampson?utm_source=medium&utm_medium=referral" rel="noopener" target="_blank" title="">Alice Hampson on <a href="https://unsplash.com?utm_source=medium&utm_medium=referral" rel="noopener" target="blank" title=")

Motivation and Mindset

While this week has been pretty awesome and enjoyable, the journey up until this point has most definitely not been a walk on a flowery path.

Let me provide you with some context about me. I’m currently a second year MSc student in Computer Science at the Delft University of Technology. I would describe myself as a (below) average developer compared to my peers. I didn’t really start programming before I got into my Bachelors. I never found the motivation to do so outside of courses.

It has been over a year now since I first heard about the mysterious phenomenon of open-source programming from a colleague. This colleague also described all the benefits, both for personal development and for my career.

My inner developer kicked in and was like “Oh that’s super awesome, I should do that so I can learn a lot and increase my chances for a job in the future!”, but then my inner student kicked in and was like “Why should I burden myself with more obligations than I already have (from university) though?”.

Fast forward a year. While I’m already improving my development skills in alternative ways, I still hadn’t touched open source in any voluntary or serious way. I expect to graduate during the Autumn of this year. Then I will get into the job market which is nothing out of the ordinary.

In these past months, however, I’ve started to take my future quite seriously. I am already exploring opportunities through career fairs, in-house days, and staying in touch with companies.

While this is great and all, there’s still one thing that I lack: experience. Especially in a established environment (like a company). While a part-time job on the side is an option, the main thing on my mind right now is to focus on my MSc thesis and graduate. Everything else is just kinda of on the side. So, in the end, I don’t really consider a part-time job to be an option for me.

During these months, I’ve looked for alternative opportunities to gain experience. I have looked into hobby projects and a small programming side job at the university. Those still aren’t quite what I’m looking for.

But one day, the thought came across my mind that I could gain the experience that I was looking for through open-source contributions. Provided that I chose the projects carefully to meet my needs. Because, in the end, open-source projects are very similar to companies. The only difference is that the employees are fighting to get work, rather than to avoid it. ?

After this week, I’ve noticed how my mindset and motivation has changed compared to last year. I credit this change as the reason that I could get into open source now. The lack of motivation is the reason that I failed before.

Before, I only thought about it as a way to improve my résumé. This relates to how I initially saw it as an obligation. In the long run, that would never keep me motivated. Even worse, it would never motivate me enough to begin in the first place, which is exactly what was the case during this year.

Now, on one hand I see it as an alternative way to obtain experience in a company-like environment. But more than that, I want to enhance and develop my skills, both in programming and communication.

And that’s the main thing that keeps me going right now. I can actually motivate myself to spend time doing open-source programming. Not because then I can apply for that particular job offer. Not because I can then put it on my résumé…but because I actually want to become a better developer myself. It’s all for myself. That is a motivation that will most definitely not suddenly fade out or not be strong enough.

The best practical example of this in practice is the context of my first contribution. On a Thursday (the 19th of April) I was basically working at my uni job the entire day. It was a pretty early morning for my standards, starting at 10:00 which means waking up at 8:00 for me. And we didn’t finish until 18:30, which made it a pretty long day. After coming back home and finishing dinner, it was basically already 20:00. Any other day, I would’ve either fallen asleep on the couch or taken it chill the rest of the evening.

That evening, however, a certain Github issue reached my mailbox. (I will discuss later why and how it got there ?). It caught my attention because it felt like something I could solve. I basically rushed to my laptop, and left a message on the issue that I would be willing to give it a try.

I spent a few hours working on it, before eventually hitting my friend up to play some games as usual. Even when I think back about it now, I’m still extremely surprised that I was willing to do more programming after such a long day for my standards. Again, I credit all this to the above stated change in mindset and motivation.

My Choice of Projects

As I said before, the Open Source Guides already covers a lot of the initial steps for getting into Open Source programming. They even include how to find a project to contribute to. Therefore, this section will be dedicated to my choices in projects, my preferences, and how it affected my choices.

At the moment, my main interest and the field that I’m focusing on improving the most in is web development. Especially React — it’s the library that I’ve come to love and feel most comfortable with. So naturally, I wanted to find projects that were related to web development. For me, the project being written (partially) in JavaScript was a must, while involving or being related to React was a plus.

On top of that, I wanted the project to be a slightly- to decently-established project in the community. I wanted to mimic the experience of working in a company-like environment. And being able to say that you worked on -insert widely used library or project in the community- definitely sounds cool in any conversation or interview ?.

The full list of projects that I looked into consisted of projects found through searching “React” on Github and ones that I knew or had heard of: React, Redux, MobX, React-Router, Next.js, styled-components, Storybook, Spectrum, and more…

In the end, I stuck to styled-components, Storybook, and Spectrum. Mainly because the other projects felt relatively abstract and more difficult to understand. These projects were very new-contributor friendly. Plus they are still widely used in the community.

Over that one week, and between these 3 projects, all but one of my contributions were towards Storybook. My first contribution was towards Storybook, and I really liked the flow of it. At that time there happened to be more issues that I felt I was capable of tackling, so I continued with it!

Making My First Contribution

So I’ve already talked about the context of my first contribution. I haven’t talked about the technical details of the Pull Request (PR), however. Or how I got to the PR in the first place, which will be the focus of this section.

The best thing that I did to increase my knowledge and understanding of all the projects was watching all the repositories that I was interested in. This is also the biggest recommendation that I can give to people that are new, like I am, to any open-source project. This spammed my mailbox with any activity in the projects, be it the creation of an issue or PR, or any comment in it.

Then, whenever I had some free time on my hands, I would go through all the emails. I would process the ones that I could understand. Someone made a PR and the title doesn’t sound like complete magic? Let me take a look at what they did and how. Oh, there’s a active discussion going on in this issue and it doesn’t sound overwhelming? Let’s follow that conversation as well!

The pattern here is that I tried to extract as much information and knowledge about the project by exposing myself to what others were doing. Watching the repository guaranteed that any information I was consuming would be recent.

The current problem or implementation that I was learning about was useful for the project at that point. Of course, there were scenarios where, no matter how hard I tried, I just couldn’t see myself participating meaningfully. Although this can feel very demotivating, it’s also completely normal if you think about it carefully.

In the beginning, I was archiving a lot of emails, because I just lacked the knowledge to understand the issue. Instead, I focused on the ones I could and the ones that I wasn’t sure about whether I could. No matter what the result was, I would just try to go through them and understand.

If I couldn’t, then I would know where my limitations were and still learned about the project in some way or another. If I could, then I extended my knowledge on the project as well, and I could potentially contribute to solving the issue. Of course, especially if the project was very active, it was very hard to keep up with all the emails. I just tried as much as I could afford, hoping it would help me in the long run — which it did!

At some point, someone opened an issue. The issue described some problems with the Storybook CLI during the installation process. It turned out that Storybook prefers to use yarn. However, not everybody uses yarn, and npm is still significantly used in the field.

To cover for these cases, the CLI would run the yarn — version command to check whether yarn was installed. If so, it would use it as the package manger of choice to install dependencies. The issue arose, however, when developers had both package managers installed, but mainly used npm. Storybook would then use the old version of yarn. This resulted in the issues reported by the current user.

This sounded like something that I understood and felt capable of fixing! So what did I do then? I started of with politely asking whether it was okay for me to tackle this issue.

There are several reasons that I explicitly asked this, rather than just doing it.

1. It signals than somebody is working on the issue, which is great for the maintainers.
2. It clarifies that you are working on it and that you claimed the issue. This is especially useful in highly active projects.
3. It makes sure that you’re not taking someone else’s issue. For various reasons, someone could be already working on it, and I personally hate taking away someone’s issue.
4. It will make sure that you’re not going to waste your time and effort on something that’s outdated, unnecessary, unwanted, or already done. If any of these are true, a maintainer will most likely let you know.
5. It never hurts to be polite and communicate ?.

After receiving a green light from a maintainer and the user that reported the issue, I went and applied a fix described in the issue. The fix itself wasn’t particularly mind blowing. Instead of checking for an installed version of yarn, it would check for the presence of a yarn.lock file instead. After some discussion on making the check slightly more elaborate and processing that feedback, they approved my changes. My PR was merged! ?

Did I feel super accomplished after this? You would expect so, but I actually felt way less excited about it than expected. Don’t get me wrong, it did feel satisfying to have my changes merged. It just didn’t feel like it was a super complex problem that I solved.

The real feeling of accomplishment and excitement actually came way later at unexpected moments. At multiple points in time, people would report certain problems that they had with Storybook. For me, those seemed completely unrelated to my changes. However, in at least 4 different issues, my fix was mentioned by a maintainer because it helped solve the issue at hand.

WHAT!? I ACTUALLY HELPED PEOPLE!? ? My small fix that felt like it was nothing actually helped people with their problems. The feeling of accomplishment and excitement that I had at that moment was indescribable. It exceeded any feeling that I could’ve had from solving a super complex problem of some kind. I still hold it very dear.

The Rest of the Week

After that moment, I felt even more motivation to keep working on issues and stuff in the project. As long as it was something that could help the users of Storybook, I was more than happy to have a go at it.

I paid more and more attention to the different activities in the repository. Whenever I found something I could do, I would politely ask whether it was okay for me to solve, and then make an attempt at solving it.

In my first week, I had opened 4 PR’s to Storybook, and all of them were accepted and merged! If you’re interested in the details on those PR’s, go ahead and check out the GitHub tracker.

I also want to go back briefly and further discuss the point that I made regarding watching the repositories and following all the activities in them. You might wonder whether it will pay off or be worth it for the required effort and time (which I agree is significant).

For me, the answer was a decisive yes, and this is why. My second PR had to do with a section of the codebase that I didn’t know and had never yet looked at. This, of course, was true for every part of the project as I was a new contributor. While I could find my way through the CLI code, this time it involved the actual Storybook application, which for me was on another level.

The main reason I was able to address the problem and work with the code anyway was because I went through the changes of someone else’s PR that touched upon that same part of the codebase. The style of my changes, if you compare it to the changes of that PR, were therefore very similar. But in the end, I still got the job done, and that’s all that mattered for me (and the project)!

But if I never took the time and effort to go through as much activity from the project as I could, including the work of others, I’m pretty sure I would’ve never been able to solve the issue (so quickly). So yes, if you’re serious about wanting to contribute to the project, then it’s definitely worth your time and effort.

What I Learned

To be honest, I haven’t really (yet) learned as much or improved as much in my programming this week as I expected. But don’t get me wrong — I’ve definitely learned some technical things, especially regarding how a significant project looks in practice.

Rather, I’ve learned a lot about working together with others. I’ve learned about communicating my thoughts and changes to the maintainers that had to review my changes. I’ve learned how to phrase my thoughts to get my ideas across.

In a way, this was the experience that I was looking for. Looking back onto this week, it has been super helpful. I’ve learned a lot, finally did something that I wanted to do for a long time, and, most important of all, I had fun!

Going Forward

Going forward after this week and beyond, I will just do as I’ve done during this first week: keep an eye out on issues and conversations, and help wherever and whenever I can.

As time progresses, I hope be able to also contribute to more complex problems. Ideally, it would be super awesome for me to be able to contribute to something larger, like an additional feature or add-on to Storybook. Nonetheless, I enjoy what I’m doing, and will definitely stick around and continuing doing so.

As a matter of fact, I’ve stuck around so long that at the time that I’m finishing this post (~5 weeks after I started writing this) I was invited by the owner of Storybook to join the GitHub organization! ? I’m super grateful for this opportunity. I will definitely to try my best to make myself more and more useful to the project! ?

TLDR:

• Think about what you want to accomplish with open source. If it’s not a long-term motivation, it will be hard to 1) get started and 2) keep going.
• Watch all the activity from repositories that you’re interested in and try to spend time going through them. It will considerably increase your knowledge on the project and help you contribute.
• Stay polite and have fun! ??

Thank you for reading. If you enjoyed my story, consider clapping for it a bit, sharing it with other people, or following me either here or on Twitter (or both ?). I will try my best to deliver similar content in the future!

If you have any feedback, either writing or content-wise, feel free to contact me in any of the described ways. I’m open to any feedback that will improve the quality and usefulness of my potential future content!

Special thanks to Maurício Aniche and Martijn Steenbergen for helping me out with this post through proofreading and feedback! Also to Norbert de Langen (Storybook’s maintainer), for inviting me to the GitHub org and trying his best to involve me in the project!