bit Documentation

AI-powered development workspaces with reusable components, architectural clarity and zero overhead.

18,454 stars TypeScript TypeScript 1 file · ~5,680 tokens #ai#collaboration#component-driven#composable#composable-architecture#distributed#front-end#javascript
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy bit on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name bit --restart always teambit/bit:latest

1. Project Overview & Quickstart (teambit/bit)

File: README.md





Bit is the build system to connect components and apps from development to CI in the AI era. Bit organizes source code into composable components, empowering to build reliable, scalable and consistent applications. It enables AI agents to intelligenly create and reuse components via MCP preventing duplication and accelerating development.

⚡ Features

  • Reusable components. Create reusable UI components and modules to reuse across your software.
  • Standard building blocks. Define the blueprints templates for creating components for devs and AI as one.
  • Shell applications. Compose reusable components and features into application shells.
  • Atomic and safe deployments. Ensure simple, safe and optimized deployments of apps and services for testing and production.

Bit supports all tooling in the JS ecosystem and comes out of the box with official dev environments for NodeJS, React, Angular, Vue, React Native, NextJS and far more. All are native to TypeScript and ESM and equipped with the best dev tooling.

Bit is a fit to every codebase structure. You can use Bit components in a monorepo, polyrepo, or even without repositories at all.

Getting started

Install Bit

Use the Bit installer to install Bit to be available on your PATH.

bash
npx @teambit/bvm install

Initialize Bit on a new folder or in an existing project by running the following command:

bash
bit init --default-scope my-org.my-project

Make sure to create your scope on the Bit platform and use the right org and project name. After running the command, Bit is initialized on the chosen directory, and ready to be used via Bit commands, AI agent, your editor or the Bit UI!

Create shell application

Create the application shell to run, compose and deploy your application:

bash
bit create react-app corporate-website

Run the platform:

text
bit run corporate-website

Head to http://localhost:3000 to view your application shell. You can start composing the application layout and specific pages to build your application. Learn more on building shell applications.

Compose components

Create the components to compose into the feature. Run the following command to create a new React UI component for the application login route:

text
bit create react pages/login

Find simple guides for creating NodeJS modules, UI components and apps, backend services and more on the Create Component docs.

Compose the component into the application shell:

ts
import { Login } from '@my-org/users.pages.login';
import { Routes, Route } from 'react-router-dom';

export function CorporateWebsite() {
  return (
    <AcmeTheme>
      <NavigationProvider>
        <Routes>
          <Route path="/" element={Hello world} />
          <Route path="/login" element={<Login />} />
        </Routes>
      </NavigationProvider>
    </AcmeTheme>
  );
}

Head to http://localhost:3000/login to view your new login page.
You can use bit templates to list official templates or find guides for creating React hooks, backend services, NodeJS modules, UI components and more on our create components docs. Optionally, use bit start to run the Bit UI to preview components in isolation.

Release and deploy

You can either use hosted scopes on Bit Cloud or by hosting scopes on your own. Use the following command to create your Bit Cloud account and your first scope.

bash
bit login

Use semantic versioning to version your components:

bash
bit tag --message "my first release" --major

By default, Bit uses Ripple CI to build components. You can use the --build flag to build the components on the local machine. To tag and export from your CI of choice to automate the release process or use our official CI scripts.

After versioning, you can proceed to release your components:

bash
bit export

Modernize existing projects

Head over to your bit.cloud account to see your components build progress. Once the build process is completed, the components will be available for use using standard package managers:

bash
npm install @my-org/users.pages.login

Next steps

Contributors

Bit is entirely built with Bit and you can find all its components on Bit Cloud.

Your contribution, no matter how big or small, is much appreciated. Before contributing, please read the code of conduct.

See Contributing.

License

Apache License, Version 2.0

File: components/legacy/utils/checksum/readme.md

This is a wrapper around the checksum package to make the checksumFile promise based

File: components/legacy/scope/README.md

Scope

Scope stores the components and their metadata compressed in the filesystem as "object". A scope can be local, along side the workspace, saved in .git/bit/.bit directory. Or it can be on a remote, which gets created by bit init --bare.

To push/pull objects from the remote, use bit export, bit import and bit fetch. To see the list of the components in the scope, use bit list or the low-level bit cat-scope commands.

When importing components to a scope, normally, Bit brings all its flattened-dependencies, which is the direct dependencies and their dependencies recursively. Also, during the export process, once a component is pushed to a remote, Bit imports all the missing flattened dependencies of that component. This protects the user in case one of the indirect dependency got deleted or its scope is down (the historic "pad-left" case).

Objects

  • Component - has the main data about the component, such as, name, scope-name, head-hash and a list of tags:hashes.
  • Version - represents a snap. has the source file hashes, dependencies data, build data, etc.
  • Source - source-file/dist-file.
  • Lane - component ids and their heads of the lane.
  • LaneHistory - aggregation of all changes done to a lane.
  • ExportMetadata - deprecated since 0.0.928. (see #6758).

Write objects to the FS

During export - see export-scope-components.saveObjects().
During import - see ObjectsWritable class.
If you add a new object and it needs merging, make sure it's properly handled in both of them and also add it to ObjectList.objectTypesRequireMerge.

Export Process

The main challenge in the export process is to keep the scopes consistent when exporting to multiple scopes. a user can export components belong to different scopes with cycle dependencies between them. For example. scopeA/compA depends on scopeB/compB that depends on scopeA/compA. If we persist the data of scopeA/compA but fail during the persist of scopeB/compA, users that import compA will get the an invalid component as its dependency compB is missing.

Since Bit is distributed, there is no central place to make the persist of all scopes at once. It requires some extra steps to ensure the data integrity.

The following steps are executed during the export:

  1. data transfer - the components are exported to the different scopes and stored in a temporarily directory pending-object/<export-id> on the remote. This is a non-blocking step, meaning, multiple clients can enter to this steps simultaneously.
  2. validation - validate that the objects can be merged with no errors such as merge-conflict or component-needs-update. This is where the 'lock' starts. if there are multiple export-ids, only the first one is allowed to enter this step, the rest get an ServerIsBusy exception. The reason for locking is that if two clients export at the same time and validate at the same time on the same component, since they validate against the stored component, both can succeed but after saving one of them, the other would get a conflict error during the persist, which we want to avoid at all cost. In case anything goes wrong in this step, the pending-object of this export-id is deleted for all scopes to release the resources.
  3. persist - load the data from pending-objects and save them in the objects, the components and lanes are merged carefully to not loose any local data. If the persist of a scope completed successfully, it deletes the pending-object dir to free the resource.
    If it failed, the pending-objects are not deleted, so no other export could push data until this export completes. To be able to resume this failed persist, the user can re-run the export with --resume <export-id> flag. To make sure the scopes are not locked forever in case the user who ran the export is not available, a command bit resume-export <export-id> <remotes...> can be running outside of the original workspace.
  4. import-missing-dependencies - as described above in the "scope" section, this is to make sure the remote scope has all flattened-dependencies of the exported components. In case there is an error in this step, the process continues and the export is not cancelled.

Once all steps are completed, Bit updates the .bitmap file with the new versions and the objects if needed.
The data transferred to the server is minimal, since Bit saves the locally tagged/snapped hashes, it knows to export only those. To override this and export all tags/snaps of a component, use --all-versions flag.

Import Process

TBD. See https://github.com/teambit/bit/pull/3656 for new changes here.

File: scopes/harmony/config/readme.md

WIP
this was cherry picked from another branch, so it doesn't contain all the logic.
please do not touch:)

File: scopes/docs/docs/docs.docs.mdx

labels: ['core aspect', 'bit', 'docs']

import DocsOverview from '@teambit/docs.content.docs-overview';

File: scopes/dependencies/dependencies/dependencies-loader/README.md

Dependencies Cache Mechanism

To improve component-loading performance, the dependencies data is cached in the filesystem.

The component's cache gets invalidated in the following scenario:

  1. The component-dir or sub-dirs have been changed. (modified-date of the dirs paths)
  2. One of the component files have been changed.
  3. A component config file (component.json/package.json) has modified.

The entire cache of all component dependencies is invalidated if one of the following happened:

  1. workspace-config file (workspace.jsonc) has changed.
  2. package.json file has changed.
  3. node_modules-dir (only root dir, not sub-dirs) has changed. - not sure if needed.
  4. On completion of "bit link".
  5. On completion of "bit install".
  6. During 'bit tag --persist', before loading the components.

A component is not entered to the cache in the first place in the following cases:

  1. No root-dir/track-dir (legacy).
  2. Component has one of the following issues: missingPackagesDependenciesOnFs, untrackedDependencies.

Limitations:

  1. If a user deleted the dists directories of a component in node-modules, we don't know about it and bit-status won't show any error.
  2. If a user deleted a package from node-modules dir manually, we don't know about it.

Disabling the cache

set the "no-fs-cache" feature.
For one command, prefix your command with BIT_FEATURES=no-fs-cache.
Or you can configure it on the machine level for all commands/workspaces: bit config set features='no-fs-cache'

File: scripts/docker-teambit-bit/README.md

Docker containers for bit harmony.

This dockers are not dealing with legacy bit (pre-harmony) for legacy bit please refer to bit-docker

Structure

  • Dockerfile-bit: A docker file which installs bvm and then uses bvm to install bit. This docker is usually useful for running bit commands like tag and export on CI machine
  • Dockerfile-bit-server: A docker file based on the Dockerfile-bit (using from) which creates a bare scope, and initializes the bit server on it (bit start)
  • Dockerfile-symphony: For internal use only

Using from Dockerhub

The docker images hosted on Dockerhub on those links Dockerfile-bit and Dockerfile-bit-server

Building locally

  1. cd scripts/docker-teambit-bit
  2. first build the bit docker - docker build -f ./Dockerfile-bit -t bitcli/bit:latest .
  3. second build the bit server docker - docker build -f ./Dockerfile-bit-server -t bitcli/bit-server:latest .

Running containers

Run the cli container

  1. docker run -it bitcli/bit:latest /bin/bash
  2. bit -v to see bit's version to make sure it works

Run the server container

  1. docker run -it -p {host-port}:3000 bitcli/bit-server:latest - replace the host port with the port you want to use on your host machine, for example 5000
  2. browse http://localhost:{host-port} and make sure you see the bit's ui

Exporting components to bit server

  1. Make sure you run the server container and validate it works
  2. On your local workspace run bit remote add http://localhost:{host-port} you should get a message saying remote-scope was added
  3. Set remote-scope on your workspace.jsonc as defaultScope
  4. Run bit export

Advanced usage

Using specific version of bit on the bit server

Bit server is getting a BIT_VERSION argument which is used in the FROM statement. You can use it with docker build -f ./Dockerfile-bit-server --build-arg BIT_VERSION={version} -t bitcli/bit-server:{version} .
This will make your server to fetch the cli container from Dockerhub with the specified version

Change bare scope name and location on the server container

The scope name is defined by the folder name of the containing scope (remote-scope by default).
This name is then later used for setting it up in the workspace.jsonc file.
In case you want to change it you can pass the build arg called SCOPE_PATH like --build-arg SCOPE_PATH=/root/custom-remote-scope

Using volume to make sure data is persisted

In order to persist the scope data, you want the scope folder to live outside the container in the host machine.
You can use bind mounts to do so:
docker run -it -v {scope-path-on-host}:/root/remote-scope -p {host-port}:3000 bitcli/bit-server:latest

Usually it's better to use volumes than bind mounts, or even handle the mounts by an orchestrator like Kubernetes but this topics is out of the scope in this guide

Combining scope volume with scope name/location

When combining change of the scope name/location and volume you have to make sure the location provided in the SCOPE_PATH in the build arg is matching the target in the volume:
docker run -it -v {scope-path-on-host}:/root/custom-remote-scope -build-arg SCOPE_PATH=/root/custom-remote-scope -p {host-port}:3000 bitcli/bit-server:latest
See the /root/custom-remote-scope is used both in the -v arg after the : and as the SCOPE_PATH value.

Watch bit server logs on host machine

Since the bit start command at the moment can't be run as detached, you will need a way to run it as the main command and to monitor the logs at the same time.
In order to do so, we will connect the logs dir on the container to a dir in the host using bind mounts.
In order to watch the bit logs, you will need to mount the logs directory in the host machine. like this:
docker run -it -v {logs-dir-on-host}:/root/Library/Caches/Bit/logs -p {host-port}:3000 bitcli/bit-server:latest
An example with actual values (use /root/bit-server-docker-logs for logs on host and port 5000 on host):
docker run -it -v /root/bit-server-docker-logs:/root/Library/Caches/Bit/logs -p 5000:3000 bitcli/bit-server:latest

In most cases it make sense to use tmpfs-mounts for this, but this as well is out of the scope for this guide

Important notes

  • Do not mount the same scope directory on the host to multiple bit-server containers.
    Bit is using different in memory cache mechanism, so mount the same dir into different servers instances, might produce unpredictable outcome.

Troubleshooting

  • Problem: Running bit start on the server container is killed with code 137
    Solution: Increase the memory provided by the host machine (usually 4GB should be enough - this is also the value we provide for the node process by NODE_OPTIONS=--max_old_space_size=4096). For example in mac - docker for mac resources

File: scripts/docker-teambit-bit/README-zh.md

Docker 容器运行 bit harmony

这些 Docker 容器不处理旧版的 bit (pre-harmony),对于旧版的 bit 请参考 bit-docker

结构

  • Dockerfile-bit：一个安装 bvm 然后使用 bvm 安装 bit 的 Dockerfile。这个 Docker 通常用来在 CI 机器上运行如 tag 和 export 的 bit 命令。
  • Dockerfile-bit-server：基于 Dockerfile-bit 的 Dockerfile。它创建一个空的 scope，并在其上初始化 bit 服务器 (bit start)。
  • Dockerfile-symphony：仅供内部使用。

从 Dockerhub 使用

Docker 镜像托管在 Dockerhub，链接是 Dockerfile-bit 和 Dockerfile-bit-server。

本地构建

  1. cd scripts/docker-teambit-bit
  2. 首先构建 bit docker - docker build -f ./Dockerfile-bit -t bitcli/bit:latest .
  3. 其次构建 bit server docker - docker build -f ./Dockerfile-bit-server -t bitcli/bit-server:latest .

运行容器

运行 cli 容器

  1. docker run -it bitcli/bit:latest /bin/bash
  2. bit -v 查看 bit 版本以确保工作正常。

运行 server 容器

  1. docker run -it -p {host-port}:3000 bitcli/bit-server:latest - 将 {host-port} 替换为主机要使用的端口，例如 5000。
  2. 浏览 http://localhost:{host-port} 并确保可以看到 bit 的界面。

导出组件到 bit 服务器

  1. 确保运行了 server 容器并验证它可用。
  2. 在本地工作空间运行 bit remote add http://localhost:{host-port}，应该会看到 remote-scope 已添加的消息。
  3. 在 workspace.jsonc 中将 remote-scope 设为 defaultScope。
  4. 运行 bit export。

高级用法

在 bit 服务器上使用特定版本的 bit

Bit 服务器会读取一个用于 FROM 语句的参数 BIT_VERSION。你可以通过 docker build -f ./Dockerfile-bit-server --build-arg BIT_VERSION={version} -t bitcli/bit-server:{version} . 来使用它。这会让你的服务器从 Dockerhub 获取指定版本的 cli 容器。

改变 server 容器上的空 scope 名称和位置

scope 的名称由包含 scope 的文件夹名称定义(默认为 remote-scope)。这个名称后来会被设置于 workspace.jsonc 文件中。如果要更改，可以传递名为 SCOPE_PATH 的构建参数，如 --build-arg SCOPE_PATH=/root/custom-remote-scope。

通过 volume 确保数据持久化

为了使 scope 数据持久化，你需要将 scope 文件夹放置在容器外的主机上。你可以通过绑定挂载来实现：docker run -it -v {scope-path-on-host}:/root/remote-scope -p {host-port}:3000 bitcli/bit-server:latest。

通常使用 volume 比绑定挂载好，甚至可以由诸如 Kubernetes 之类的编排器来处理挂载，但这超出了本指南讨论的范围。

将 scope volume 和 scope 名称/位置相绑定

当同时更改 scope 名称/位置和 volume 时，你需要确保构建参数 SCOPE_PATH 中提供的位置与 volume 中的目标匹配：docker run -it -v {scope-path-on-host}:/root/custom-remote-scope -build-arg SCOPE_PATH=/root/custom-remote-scope -p {host-port}:3000 bitcli/bit-server:latest。请注意 /root/custom-remote-scope 既用在了 -v 参数的 : 之后，又用于了 SCOPE_PATH 的值。

在主机上观察 bit 服务器日志

由于目前 bit start 命令无法以分离方式运行，因此需要一种方法同时将其作为主命令运行且监控日志。为此，我们将使用绑定挂载将容器上的日志目录连接到主机上的目录。为了观察 bit 日志，你需要挂载主机上的日志目录，如：docker run -it -v {logs-dir-on-host}:/root/Library/Caches/Bit/logs -p {host-port}:3000 bitcli/bit-server:latest。举一个实际的例子 (在主机上使用 /root/bit-server-docker-logs 作为日志目录，主机端口为 5000)：docker run -it -v /root/bit-server-docker-logs:/root/Library/Caches/Bit/logs -p 5000:3000 bitcli/bit-server:latest。

在大多数情况下，最好对此使用 tmpfs 挂载，但这也超出了本指南讨论的范围。

重要提示

  • 不要将同一个 scope 目录挂载到多个 bit server 容器上。
    Bit 使用不同的内存缓存机制，因此将同一目录挂载到不同的服务器实例上可能会产生不可预测的结果。

故障排除

  • 问题：在 server 容器上运行 bit start 时被杀死，代码为 137。
    解决方案：增加主机提供的内存量 (通常 4GB 就足够了——这也是我们为节点进程提供的内存大小 NODE_OPTIONS=--max_old_space_size=4096)。例如在 Mac 上：docker for mac resources。

2. Official Technical Reference & Guides (teambit/docs)

bit.dev docs

This repo contains the source code and documentation powering docs.bit.dev.
The website is based on Docusaurus

Getting started

Installation

  1. npm i to install top level dependencies

Running locally

  1. cd website to go into the project root
  2. npm i to install the website's npm dependencies
  3. npm run start to start the development server with docs hot reloading
  4. or npm run watch to start the development server with structure changes hot reloading (slower)
  5. open http://localhost:3000 to open the site in your browser

Contributing

Contributions are always welcome, no matter how large or small. Before contributing, please read the code of conduct.

You can just hit the "Edit" button on each page to make change to the content of the page.

Images should be placed in the docs/assets files and be linked into.

License

MIT License.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#ai Browse ai catalog → #collaboration Browse collaboration catalog → #component-driven Browse component-driven catalog → #composable Browse composable catalog → #composable-architecture Browse composable-architecture catalog → #distributed Browse distributed catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →