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:


The output should be the following:

successfully initialized a bit workspace.

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:


The output displays the port for the UI server:

You can now view 'my-workspace' components in the browser. Bit server is running on http://localhost:3000

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

an empty workspace

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


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


Track a directory as a component

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:


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.

See command synopsis

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:

See command synopsis

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

id │
scope │
name │ hello-world
env │ teambit.harmony/node
package name │ @my-org/my-scope.hello-world
deprecated │ false
main file │ hello-world.ts
files │ constants.ts
│ hello-world.ts
aspects │ teambit.component/dev-files
│ teambit.compositions/compositions
│ teambit.dependencies/dependency-resolver
│ teambit.envs/envs
│ teambit.pkg/pkg
│ teambit.preview/preview
dependencies │ lodash@^4.17.21- (package)

Learn more about Bit components in the Create components page.


Relative paths

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';

Dependency installation

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"

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

Development environment ('env')

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.

Collaborate with git

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