This article is outdated.
To learn how to build a React component library using Bit Harmony, see here:
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 😎
Top comments (2)
Why is the answer always bit?
I am part of Bit's team. I've now added a disclaimer at the beginning of my post (I should have done that earlier). I've also mentioned that I don't know of any other tool that enables building truly modular libraries. If you know of anything else, I would love to hear.