Repository: teambit/bit

Stars: 18377

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Additional Bit Workflow Instructions Copy Chapter

For comprehensive Bit MCP workflow instructions and core principles, see: .github/instructions/bit.instructions.md

CLI Output Style Guide Copy Chapter

When modifying CLI command output, follow the style guide: scopes/harmony/cli/cli-output-style-guide.md

Use the shared formatting toolkit from @teambit/cli (scopes/harmony/cli/output-formatter.ts) — never hardcode chalk styles for section titles or Unicode symbols.

Development Commands Copy Chapter

IMPORTANT: This repository practices "dogfooding" - Bit is built using Bit itself. Always use bit commands rather than direct npm/pnpm commands where possible.

Setup and Installation Copy Section

- npm run full-setup - Complete setup for the repository (installs dependencies, sets up husky, compiles)
- npm run setup - Basic setup (bit install and compile)
- bit install - Install dependencies (uses PNPM under the hood, never run pnpm install directly)
- npm run dev-link [alias] - Creates a global symlink for the bit binary (default: bit-dev)

Build and Compilation Copy Section

- bit compile - Compile all components
- bit watch - Watch for changes and compile automatically

Testing Copy Section

- bit test - Run unit tests for components/aspects
- bit test --debug - Run unit tests in debug mode (prints workspace location, keeps workspaces)
- npm run e2e-test - Run end-to-end tests (can take hours, usually run on CI)
- npm run e2e-test:debug - Run e2e tests in debug mode (keeps workspaces, prints output)
- npm run mocha-circleci - Run mocha tests with CircleCI configuration

Running specific e2e tests:
⚠️ CRITICAL: ALWAYS add .only to the test before running e2e tests! ⚠️

- Add .only to the describe or it block (e.g., describe.only(...) or it.only(...))
- Then run npm run e2e-test or npm run e2e-test:debug
- The --grep flag does NOT work reliably - you MUST use .only
- Running without .only will execute the ENTIRE test suite which takes hours
- Example: Change describe('my test', ...) to describe.only('my test', ...)

Bug reproduction testing: When asked to reproduce a bug, create an e2e test instead of creating test directories in the current workspace. You cannot create nested Bit workspaces. E2E test helpers provide workspace creation methods that use temporary directories and automatically clean up after tests.

Linting and Formatting Copy Section

- npm run lint - Run ESLint and TypeScript type checking
- npm run lint:fix - Run ESLint with auto-fix
- npm run oxlint - Run oxlint (faster linter)
- npm run format - Format code with Prettier
- npm run prettier:check - Check if code is formatted correctly

IMPORTANT: After making code changes, always run npm run lint to verify. Do NOT run npx tsc --noEmit or npx oxlint directly — npm run lint is the canonical command and covers both type checking and linting for this repo.

Bit-specific Commands Copy Section

- bit start - Start the Bit UI for component development
- bit status - Show workspace status
- bit compile - Compile components
- bit test - Run tests
- bit tag - Tag components for release
- bit export - Export components to remote scopes

Architecture Overview Copy Chapter

Component System Copy Section

Bit is built using a component-based architecture where the entire codebase is composed of reusable components. The system follows a modular approach with:

- Aspects: Core building blocks that provide functionality across the system
- Scopes: Organizational units that group related components
- Environments: Define how components are built, tested, and bundled
- Capsules: Isolated environments for component operations

Key Directories Copy Section

Core Architecture:

- scopes/ - Contains all aspects organized by domain (harmony, component, dependencies, etc.)
- components/ - Standalone components and utilities
- e2e/ - End-to-end tests organized by functionality

Important Scopes:

- scopes/harmony/ - Core runtime and infrastructure aspects
- scopes/component/ - Component-related functionality
- scopes/compilation/ - Build and compilation aspects
- scopes/dependencies/ - Dependency management
- scopes/workspace/ - Workspace management
- scopes/scope/ - Remote scope operations

Aspect System Copy Section

Each aspect follows a standard structure:

- .aspect.ts - Aspect definition and metadata
- .main.runtime.ts - Main runtime implementation
- .ui.runtime.ts - UI runtime implementation (if applicable)
- .docs.mdx - Documentation
- .composition.tsx - Component compositions for testing

Configuration Copy Section

- workspace.jsonc - Main workspace configuration
- package.json - Node.js dependencies and scripts
- tsconfig.json - TypeScript configuration
- .bitmap - Component tracking (auto-generated)

Development Patterns Copy Section

Dependency Management:

- Uses bit install which runs PNPM programmatically under the hood
- Never run pnpm install directly - always use bit install
- bit install performs multiple operations beyond just package installation
- Strict peer dependency rules configured
- Component dependencies managed through Bit's dependency resolver

Testing Strategy:

- Unit tests: .spec.ts files alongside source
- E2E tests: Comprehensive scenarios in e2e/ directory
- Component compositions: Interactive examples in .composition.tsx

Build Process:

- TypeScript compilation with strict mode
- Babel for transpilation
- Webpack for bundling
- ESLint for linting with custom rules

Key Concepts Copy Section

Bootstrap Flow:

1. User runs a Bit command
2. Bit builds a graph of core aspects + workspace aspects
3. All aspects are loaded and instantiated
4. Aspects register CLI commands
5. Command is parsed and executed

Component Lifecycle:

- Add/Create: Components added to workspace (.bitmap updated)
- Tag/Snap: Components versioned and stored in scope
- Export: Components published to remote scopes
- Import: Components brought into workspace from remote scopes

Workspace vs Scope:

- Workspace: Development environment with source code
- Scope: Storage for versioned components (local: .bit/, remote: Bit Cloud)

Development Notes Copy Chapter

Environments Copy Section

- Components use environments for build, test, and bundle operations
- Default environments: Node.js, React, Angular, Vue
- Custom environments can be created by extending base environments

Debugging Copy Section

- Debug logs: ~/Library/Caches/Bit/logs/debug.log (macOS)
- Verbose logging: BIT_LOG=* prefix
- Stack traces written to debug.log
- Use bit globals to locate debug.log

Performance Copy Section

- Use bit watch for faster development cycles
- E2E tests run in parallel on CI
- Component compilation can be parallelized

Aspect Configuration Copy Section

- Aspects accept config as 2nd parameter in provider method: provider(deps, config)
- Define TypeScript interface for config and inject into main class constructor
- Configure in workspace.jsonc under aspect ID key

README.md Copy Chapter

<p align="center">
<img src="http://static.bit.dev/bit-docs/readme-bit-logo.png"/>
</p>

<p align="center">
<a href="https://bit.dev/">Website</a> |
<a href="https://bit.dev/docs/">Docs</a> |
<a href="https://bit.cloud/bitdev">Community</a> |
<a href="https://bit.cloud/">Bit Cloud</a>
</p>

</p>

<h3 align="center">
</h3>

<p align="center">

<p align="center">
<a href="https://opensource.org/licenses/Apache-2.0"><img alt="apache" src="https://img.shields.io/badge/License-Apache%202.0-blue.svg"></a>
<a href="https://github.com/teambit/bit/blob/master/CONTRIBUTING.md"><img alt="prs" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg"></a>
<a href="https://circleci.com/gh/teambit/bit/tree/master"><img alt="Circle Status" src="https://circleci.com/gh/teambit/bit/tree/master.svg?style=shield">
<a href="https://github.com/prettier/prettier"><img alt ="Styled with Prettier" src="https://img.shields.io/badge/styled_with-prettier-ff69b4.svg">
<a href="https://join.slack.com/t/bit-dev-community/shared_invite/zt-1vq1vcxxu-CEVobR1p9BurmW8QnQFh1w" ><img alt="Join Slack" src="https://img.shields.io/badge/Slack-Join%20Bit%20Slack-blueviolet"/></a>

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 Copy Chapter

Install Bit Copy Section

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

npx @teambit/bvm install

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

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 Copy Section

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

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.

Compose components Copy Section

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.

Compose the component into the application shell:

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={<div>Hello world</div>} />
          <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 Copy Section

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.

bit login

Use semantic versioning to version your components:

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:

bit export

Modernize existing projects Copy Section

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:

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

Next steps Copy Chapter

- Create more components
- Setup your editor
- Configure CI of choice
- Start from an existing project

Contributors Copy Chapter

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

<a href="../../graphs/contributors"><img src="https://opencollective.com/bit/contributors.svg?width=890&button=false" /></a>

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

See Contributing.

License Copy Chapter

Apache License, Version 2.0