Start from an existing project

Use Bit in your project to track directories as Bit components. Tracked directories will become discrete units of code that can be developed, shared, consumed and collaborated on, independent of the rest of your project.

Run the following at the root of your project, to initialize a Bit workspace:

$bit init

Copied

The output should be the following:

Bit has generated a workspace with the minimum necessary files, to prevent any possible conflicts with your current project. These files include the workspace.jsonc, .bitmap and the .git/.bit hidden directory.

To preview your workspace components and inspect your workspace status using the UI, run the following:

$bit start

Copied

The output displays the port for the UI server:

Head to http://localhost:3000 in your browser. Right now your workspace is empty as no component is being tracked.

At any point during your component development, run the following to get a detailed status of your workspace:

$bit status

Copied

Run the following to list the components maintained in your workspace:

$bit list

Copied

The steps to componentizing a directory are demonstrated using the following project structure. Note that this project already has a Bit workspace initialized in it:

TASKS-WORKSPACE

.git

.bit

.git/.bit/about-this-dir

hello-world

hello-world/constants.ts

hello-world/hello-world.ts

node_modules

node_modules/about-this-dir

public

bit

public/bit/about-this-dir

.bitmap

package.json

workspace.jsonc

Learn more about Bit workspaces in the Create a new workspace page.

To track a directory as a component, specify its path. Use the --main flag to specify the entry point of the component.

$bit add hello-world --main hello-world.ts

Copied

Your component is named after its directory (hello-world). To specify a different name, use the --id flag. Your component's scope is the default scope of your workspace. To specify a different scope, use the --scope flag. To learn more see, Add a directory as a component.

Run the following to inspect your component's metadata and configuration:

$bit show hello-world

Copied

The output is similar to the following. Click on the different sections below to learn about each of them.

Learn more about Bit components in the Create components page.

The dependencies of a Bit component must be Bit components or packages. Relative paths to source files in the project, outside of the component's directory, make the component coupled to its project and unusable in other projects.

Note that Bit generates a corresponding package for each Bit component, to enable the use of absolute package names instead of relative paths.

/* GOOD: an absolute path to another Bit component */
import { anotherBitComponent } from '@my-org/my-scope/another-bit-component';

/* BAD: a relative path to a file outside the component directory */
import { someModule } from '../outside-component-dir/some-module';

/* GOOD: a relative path to a file in the the same component directory */
import { module } from './module-in-same-component-dir';
Copied

To enjoy the full capabilities provided by Bit, it is recommended to use Bit for dependency installation. Bit takes into consideration the dependency config in the workspace.jsonc file as well as the project's already-existing package.json.

If you choose not to use Bit, make sure to add the following to your post-install scripts:

{
  "scripts": {
    "postinstall": "bit import && bit compile && bit link"
  }
}
Copied

bit compile compiles all components in the workspace and bit link creates symlinks from the node_module directory to components in your workspace.

An env is a component that provides a collection of tools and configurations for component development, build, and delivery. It is used only for the component's development process, and does not replace your project's development environment. New components use the Node env by default (see the bit show output above).

To set you component with a different env, see Use envs.

See the the Collaborate with git page to learn how to integrate bit with your git workflow.