Quick Start

Learn how to use Bit in a few simple steps.

These simple steps will teach you the basics you need to know for working with Bit, all the way from sharing components right from your project to using them in any other project with your favorite tools. When finished, you will also have a beatiful gallery of components ready to share with your team.

Let’s get started with these 4 quick steps:

  1. Get Bit ready.
  2. Choose components to share.
  3. Share components to your Scope.
  4. Use components in other projects.

Get Bit ready

Install bit

With NPM.

npm install bit-bin -g

With Yarn.

yarn global add bit-bin

See additional installation methods.

Tip

Once installed you can verify the installation:

bit --version

Global setup

Run these commands to configure your username and email for Bit-CLI.

bit config set user.name john
bit config set user.email john@gmail.com

Choose components to share

Init Bit for your project

Run this command to initialize Bit for your project.

cd project-directory
bit init

You can learn more about initializing Bit here.

Choose components to track

Bit can track and isolate any subset of files in your repository as a component.
You can tell Bit which components to track and it will decouple their representation from the project’s file system.
You can learn more here.

To track components use the bit add command.

bit add src/components/* # use a glob pattern or a specific path to track multiple components or a single component.

Component isolation means Bit automatically scans your components for both package and file dependencies, and creates their dependency tree while handling different use cases - Learn more.

Tip

Use the bit status command to make sure that each component’s dependency graph was successfully built and resolved by Bit.

Example

Let’s track the components button, login and logo in the following project’s directory structure.

$ tree
.
├── App.js
├── App.test.js
├── favicon.ico
├── index.js
└── src
    └── components
        ├── button
        │   ├── Button.js
        │   ├── Button.spec.js
        │   └── index.js
        ├── login
        │   ├── Login.js
        │   ├── Login.spec.js
        │   └── index.js
        └── logo
            ├── Logo.js
            ├── Logo.spec.js
            └── index.js

5 directories, 13 files

To track these files as components we’ll use the bit add command with a glob pattern.

$ bit add src/components/*
tracking 3 new components

Lock dependencies and versions

Tagging a component will apply a version for the components and lock their current state and dependency graphs. Versioning components help to create higher-level contracts for their safe reuse between repositories and projects.
You can learn more about versioning here.

$ bit tag --all 1.0.0
3 components tagged | 3 added, 0 changed, 0 auto-tagged
added components:  components/button@1.0.0, components/login@1.0.0, components/logo@1.0.0

All tracked components in your repository are now tagged with version 1.0.0.

Share components to your Scope

Create a Scope

Let’s sign-up to Bit and create a free Scope.

To make components available to from other projects Bit uses Scopes.
Scopes host your components and act as a remote source of truth to sync changes between projects.

Another great thing about Scopes is that they help you easily organize and discover components, and collaborate with others while working on different projects (like a common box of Lego).

Here is an example Scope of React components,
and an example Hero component.

Tip

Scopes can be set up on any server.
However, we recommend creating a Scope on the Bit website hub- for 5 key advantages:

  1. Instantly making every component available to install with the NPM / Yarn client.
  2. A neat UI with auto-parsed docs and examples from the component’s source code.
  3. Discoverability through a component search-engine.
  4. Isolated testing and building environments for your components with visual results.
  5. Managing permissions, collaborators etc.

Share components to your Scope

Now let’s share the tracked components to the Scope you just created.
Unlike publishing packages, this will not change the project’s source code or force you to set up any additional repositories.

$ bit export username.scopename  # Share components to this Scope
exported 3 components to scope username.scopename

That’s it!

Once shared, you can view all your components in this Scope, share them with your team and use them in all your projects.

Tip

Any team member can now install them with NPM / Yarn
in any of their projects, even if not using Bit.

Example

If my Bit username is john and my Scope is called ui-components,
then my export command will be:

$ bit export john.ui-components
exported 3 components to scope john.ui-components

Tip

You can also create and share an empty component

> cd project-directory
bit init
touch empty-component.js
bit add empty-component.js
bit tag --all
bit export username.scopename

Use components in other projects

Install with Yarn / NPM

Tip

This option completes the workflow of sharing any part of your repo as a package without changing it, and making it available any way you choose; next level modularity!

Components shared to Bit can automatically be installed with the NPM / Yarn client or with any package manager that implements the CommonJS package registry specification.

Example

Here is a React Hero component hosted on Bit.
It was published by a user called “bit”, it’s in a scope called “movie-app” under a namespace called “components” and its name is “hero”.
As you can see, its component page also provides all the instructions needed.

To install it with NPM simply configure Bit as a scoped registry:

npm config set @bit:registry https://node.bitsrc.io

And install the component:

npm i @bit/bit.movie-app.components.hero

You can also do the same for Yarn:

yarn config set "@bit:registry" "https://node.bitsrc.io/"

and then:

yarn add @bit/bit.movie-app.components.hero

Import components with Bit (distributed development)

With Bit you can source components in multiple repositories, continue to develop them and keep them synced to track and update changes. This way, Bit creates a distributed workflow that enables you to sync smaller building blocks in multiple projects while evolving them from any one of them.

This is Bit’s import command structure:

bit import remote/components/login --path src/components

This command will clone the component’s source-code into the target repository.
Changes can still be tracked and applied using bit tag.

Example

Let’s say I want to import this Hero component.
It was published by a user called “bit”, it’s in a scope called “movie-app” under a namespace called “components” and its name is “hero”.

The relevant command (as seen on its component page) would be:

bit import bit.movie-app/components/hero

That’s it!

You are now ready to work with Bit and easily share code between your projects.
Feel free to learn more through the different sections of the docs, search the Bit website for components or visit Bit on GitHub.

  • what is bit