Tutorial: Creating a Component Library with Storybook and React

Introduction

Building a component library is an essential step for any organization or project that values reusability and consistency in UI development. By creating a centralized library, you can streamline development, maintain design consistency, and speed up the process of building new features. In this tutorial, we'll guide you through the process of setting up a component library using React and Storybook, a powerful tool for developing and documenting UI components in isolation.

Prerequisites

Before we start, ensure you have the following:

• Node.js and npm/yarn installed: You'll need Node.js and a package manager like npm or yarn to manage dependencies.

• Basic knowledge of React: Familiarity with React is necessary to understand and build components.

• Git installed: We will version control our component library using Git.

Step 1: Setting Up Your Project

Let's start by setting up a new React project.

npx create-react-app my-component-library
cd my-component-library

Once your React app is set up, we can start integrating Storybook.

Step 2: Installing and Configuring Storybook

Storybook is an open-source tool that allows you to develop UI components in isolation and document them effectively. To add Storybook to your project, run the following command:

npx storybook init

This command will install Storybook and configure it for your React project. After the installation is complete, you’ll see a new .storybook directory and some example stories in the src directory.

To start Storybook, use the following command:

npm run storybook

This will open Storybook in your default web browser, displaying the example stories.

Step 3: Creating Your First Component

Let’s create a simple button component to start our library. Create a new directory called components inside the src directory:

mkdir src/components

Now, create a file for the button component:

// src/components/Button.jsx
import React from 'react';
import PropTypes from 'prop-types';
import './Button.css';

const Button = ({ label, onClick, primary }) => {
    const mode = primary ? 'btn--primary' : 'btn--secondary';
    return (
        <button className={`btn ${mode}`} onClick={onClick}>
            {label}
        </button>
    );
};

Button.propTypes = {
    label: PropTypes.string.isRequired,
    onClick: PropTypes.func,
    primary: PropTypes.bool,
};

Button.defaultProps = {
    onClick: undefined,
    primary: false,
};

export default Button;

Next, add some basic styles for your button:

/* src/components/Button.css */
.btn {
    font-size: 1rem;
    padding: 10px 20px;
    border: none;
    border-radius: 5px;
    cursor: pointer;
}

.btn--primary {
    background-color: #007bff;
    color: white;
}

.btn--secondary {
    background-color: #6c757d;
    color: white;
}

Step 4: Creating a Story for Your Component

Now that we have a button component, let's create a story for it in Storybook. Stories are the building blocks of Storybook; they represent the different states or variants of a component.

Create a file for the Button story:

// src/components/Button.stories.jsx
import React from 'react';
import Button from './Button';

export default {
    title: 'Components/Button',
    component: Button,
};

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
    primary: true,
    label: 'Primary Button',
};

export const Secondary = Template.bind({});
Secondary.args = {
    primary: false,
    label: 'Secondary Button',
};

export const WithClickHandler = Template.bind({});
WithClickHandler.args = {
    primary: true,
    label: 'Click Me',
    onClick: () => alert('Button clicked!'),
};

This story file defines three variants of the Button component: a primary button, a secondary button, and a button with a click handler.

Step 5: Running and Testing Your Stories

To see your component in action, start Storybook:

npm run storybook

Storybook will launch in your default browser, displaying your Button component in the different states defined in your stories.

Step 6: Organizing Your Component Library

As your component library grows, it's essential to keep things organized. A good practice is to group components by category and ensure that each component has its own directory, including its .jsx file, styles, and stories.

Here’s an example of how you might structure your component library:

src/
└── components/
    ├── Button/
    │   ├── Button.jsx
    │   ├── Button.css
    │   └── Button.stories.jsx
    └── Input/
        ├── Input.jsx
        ├── Input.css
        └── Input.stories.jsx

Step 7: Publishing Your Component Library

Once you’ve developed a set of components, you might want to share them with others or reuse them across different projects. You can do this by publishing your component library to npm.

First, create an account on [npm](https://www.npmjs.com/) if you don’t have one already.

Next, update your package.json to include details about your library:

{
  "name": "my-component-library",
  "version": "1.0.0",
  "main": "src/index.js",
  "scripts": {
    "build": "react-scripts build",
    "storybook": "start-storybook -p 6006",
    "build-storybook": "build-storybook"
  },
  "peerDependencies": {
    "react": "^17.0.0",
    "react-dom": "^17.0.0"
  }
}

Add an entry point for your library in src/index.js:

// src/index.js
export { default as Button } from './components/Button/Button';

Finally, publish your library to npm:

npm publish

Make sure to follow npm’s guidelines for publishing, including versioning and naming conventions.

Conclusion

Congratulations! You’ve now created a basic component library using Storybook and React. This setup allows you to build, document, and share reusable UI components efficiently. By leveraging Storybook’s powerful features, you can ensure that your components are well-documented, tested in isolation, and ready to be used across different projects.

Next Steps

Consider adding more components to your library, integrating with a design system, or automating the testing and deployment process using CI/CD tools. The more you expand and refine your component library, the more valuable it will become to your development workflow.