How to Build a Modular React Component Library

This article is outdated.

To learn how to build a React component library using Bit Harmony, see here:

Building a React Component Library — The Right Way | by Eden Ella | Bits and Pieces

Eden Ella ・ May 11, 2023 ・

Medium

A modular library or a "collection" enables new components to be added independently. That means, whenever you build a new UI component (worth sharing), you simply push it to your shared component collection. That also means each shared component is versioned individually. You don't need to update an entire library just for a small change.

It's a great way to get all the benefits of a traditional component library (reusability, UI consistency, etc), without the major overhead that's usually involved (setting up a repo, configuring packaging, setting up a documentation tool, etc.)

Most importantly, it's a way to share, use and collaborate on individual components right from any repo or codebase.

The project

Turn this:

To this:

1. Create a component collection

A collection is a scope of independent components hosted on bit.dev and registered in Bit’s registry. It is radically different from a traditional library as it only serves as a way to organize and manage sets of components. Unlike a traditional library, a collection is not a monolithic object with single versioning.

The first step for sharing components to a collection is - to create a collection 😏

For that, go to bit.dev and create your account and a new collection named (for our purpose) ‘react-demo-app’.

2. Install Bit and initialize a workspace

If you'd like to follow along, clone and install this demo to-do app:

$ git clone https://github.com/teambit/react-demo-app.git
$ cd react-demo-app
$ yarn

Install Bit CLI globally on your machine:

$ yarn global add bit-bin

Log in to your account:

$  bit login

To start working with Bit on this project - initialize a Bit workspace:

$ bit init --package-manager yarn

3. Track the app’s components

Track all the app’s components (located in the ‘components’ library):

$ bit add src/components/*

It's always best to make sure you don't have any dependency issues by typing:

$ bit status

In this case, you should see the following message:

new components
(use "bit tag --all [version]" to lock a version with all your changes)

> button ... ok
     > h1 ... ok
     > list ... ok
     > removable-list-item ... ok
     > text-input ... ok
     > to-do-list ... ok

If any component has dependency graph issues, click here to find out how to resolve them.

4. Configure a compiler

Configuring a compiler for shared components gives you the freedom to use, build and test them anywhere. You can build your own compilers for Bit or use one of Bit's pre-made ones:

$ bit import bit.envs/compilers/react --compiler

You should see:

the following component environments were installed
- bit.envs/compilers/react@1.0.5

5. Tag (stage) components

When tagging a component, Bit runs all tests related to it, compiles it and locks versioning.

In my case, I want to tag all added components:

$ bit tag --all 1.0.0

6. Export components

Once the components are tagged, they are ready to be exported to a shared collection (in this case the collection name is 'react-demo-app'):

$ bit export <username>.react-demo-app

If you followed along, your components should be available in your "react-demo-app" collection in bit.dev.

Go to https://bit.dev/user-name/react-demo-app (or explore my own collection at https://bit.dev/learn-bit/react-demo-app/) to see them rendered live in Bit’s playground. Use the playground to add examples, showing how each component could be used.

It should be noted that your components will not render in Bit's playground if you don't provide them with valid examples (so, for example, my "list" component will not render if it doesn't receive its required prop, an array of items).

I also added a CSS file (to the examples) to import the font-family I intended to use with my components.

7. Import a single component to a new project

Create a new React project using create-react-app and name it ‘new-app’.

$ npx create-react-app new-app

Let’s say your project needs a removable-list-item component.

You can install it in its built form, using NPM or Yarn, just like any other package:

$ yarn add @bit/user-name.react-demo-app.removable-list-item

Or, you may want to import its source-code and modify it. You'll first need to initialize a new Bit workspace:

$ cd new-app
$ bit init

Then, import the removable-list-item component from your collection.

$ bit import user-name.react-demo-app/removable-list-item

For example:

$ bit import bit.react-demo-app/removable-list-item

After completion, this message should appear:

successfully imported one component
- added bit.react-demo-app/removable-list-item new versions: 1.0.0, currently used version 1.0.0

The imported component is now located under the newly created components library (located in your project’s root folder — not its src folder).

├───.git
├───components
│   ├───removable-list-item

8. Modify a component and export it back

Open the source code inside the removable-list-item directory and make a small change before exporting it back as a new version.

For example, let’s add animation for every removable-list-item appearance.

This is how the removable-list-item looks before the modification:

This is how it looks after the modification:

The removable-list-item component is now an imported component. That means it is already tracked and handled by Bit (and have its compiler configured).

Let's tag things up (again, I'll use the 'all' flag just for convenience):

I can use the component I

$ bit tag --all

And push (export) it back to the shared collection:

$ bit export user-name.react-demo-app

You should receive a message stating:

exported 1 components to scope username.react-demo-app

The modified component is now available in the react-demo-app collection 😎