## 1. Project Overview & Quickstart (teambit/bit)
## File: README.md
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/teambit/bit/blob/master/CONTRIBUTING.md)
[](https://join.slack.com/t/bit-dev-community/shared_invite/zt-1vq1vcxxu-CEVobR1p9BurmW8QnQFh1w)
[Bit](https://bit.dev) 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](https://bit.dev/docs/backend-intro), [React](https://bit.dev/docs/react-intro), [Angular](https://bit.dev/docs/angular-introduction), [Vue](https://bit.dev/docs/vue-intro), [React Native](https://bit.dev/docs/react-native-intro), [NextJS](https://bit.dev/docs/quick-start/hello-world-nextjs) and [far more](https://bit.dev/docs). 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](https://bit.cloud/signup) 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](https://bit.dev/docs/getting-started/installing-bit/editor-setup) 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:
```
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](https://bit.dev/docs/getting-started/composing/create-apps).
### 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:
```
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](https://bit.dev/docs/getting-started/composing/creating-components/).
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 (
} />
);
}
```
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](https://bit.dev/docs/getting-started/composing/creating-components). 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](https://bit.cloud) or by [hosting scopes on your own](https://bit.dev/reference/scope/running-a-scope-server). 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](https://bit.cloud/products/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](https://bit.dev/docs/getting-started/collaborate/exporting-components#ci-scripts).
After versioning, you can proceed to release your components:
```bash
bit export
```
### Modernize existing projects
Head over to your [bit.cloud account](https://bit.cloud) 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
- [Create more components](https://bit.dev/docs/getting-started/composing/creating-components/)
- [Setup your editor](https://bit.dev/docs/getting-started/installing-bit/editor-setup)
- [Configure CI of choice](https://bit.dev/docs/getting-started/collaborate/exporting-components/#ci-scripts)
- [Start from an existing project](https://bit.dev/docs/getting-started/installing-bit/start-from-existing-project)
## Contributors
Bit is entirely built with Bit and you can find all its components on [Bit Cloud](https://bit.cloud/teambit/~scopes).
[](../../graphs/contributors)
Your contribution, no matter how big or small, is much appreciated. Before contributing, please read the [code of conduct](CODE_OF_CONDUCT.md).
See [Contributing](CONTRIBUTING.md).
## License
[Apache License, Version 2.0](https://github.com/teambit/bit/blob/master/LICENSE)
---
## File: components/legacy/utils/checksum/readme.md
This is a wrapper around the [checksum](https://www.npmjs.com/package/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/` 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 ` 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 ` 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](https://github.com/teambit/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](https://hub.docker.com/r/bitcli/bit) and [Dockerfile-bit-server](https://hub.docker.com/r/bitcli/bit-server)
## Building locally
1. `cd scripts/docker-teambit-bit`
1. first build the bit docker - `docker build -f ./Dockerfile-bit -t bitcli/bit:latest .`
1. 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`
1. `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
1. 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](https://docs.docker.com/storage/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](https://docs.docker.com/storage/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](https://docs.docker.com/storage/tmpfs/) 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](https://docs.docker.com/docker-for-mac/#resources)
---
## File: scripts/docker-teambit-bit/README-zh.md
# Docker 容器运行 bit harmony
_这些 Docker 容器不处理旧版的 bit (pre-harmony),对于旧版的 bit 请参考 [bit-docker](https://github.com/teambit/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](https://hub.docker.com/r/bitcli/bit) 和 [Dockerfile-bit-server](https://hub.docker.com/r/bitcli/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 文件夹放置在容器外的主机上。你可以通过[绑定挂载](https://docs.docker.com/storage/bind-mounts/)来实现：`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` 命令无法以分离方式运行，因此需要一种方法同时将其作为主命令运行且监控日志。为此，我们将使用[绑定挂载](https://docs.docker.com/storage/bind-mounts/)将容器上的日志目录连接到主机上的目录。为了观察 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 挂载](https://docs.docker.com/storage/tmpfs/)，但这也超出了本指南讨论的范围。_
## 重要提示
- 不要将同一个 scope 目录挂载到多个 bit server 容器上。
Bit 使用不同的内存缓存机制，因此将同一目录挂载到不同的服务器实例上可能会产生不可预测的结果。
## 故障排除
- **问题**：在 server 容器上运行 bit start 时被杀死，代码为 137。
**解决方案**：增加主机提供的内存量 (通常 4GB 就足够了——这也是我们为节点进程提供的内存大小 `NODE_OPTIONS=--max_old_space_size=4096`)。例如在 Mac 上：[docker for mac resources](https://docs.docker.com/docker-for-mac/#resources)。
## 2. Official Technical Reference & Guides (teambit/docs)
[](https://join.slack.com/t/bit-dev-community/shared_invite/zt-o2tim18y-UzwOCFdTafmFKEqm2tXE4w)
# bit.dev docs
This repo contains the source code and documentation powering [docs.bit.dev](https://docs.bit.dev/).
The website is based on [Docusaurus](https://docusaurus.io/en/)
## Getting started
### Installation
1. `npm i` to install top level dependencies
### Running locally
1. `cd website` to go into the project root
1. `npm i` to install the website's npm dependencies
1. `npm run start` to start the development server with docs hot reloading
1. or `npm run watch` to start the development server with structure changes hot reloading (slower)
1. `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](CODE_OF_CONDUCT.md).
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.