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:
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:
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:
Run the following to list the components maintained in your workspace:
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.
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:
The output is similar to the following. Click on the different sections below to learn about each of them.
│ id │ my-org.my-scope/hello-world │
├──────────────────┼──────────────────────────────────────────┤
│ scope │ my-org.my-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.docs/docs │
│ │ 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.
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.