DOCSEARCHbyAlgolia
Submit Docs

Bit

repository·master·Indexed 12 days ago

https://github.com/teambit/bit

A build system designed to organize source code into composable, reusable components and applications. Bit bridges the gap between development and CI, enabling scalable component management, semantic versioning via the Bit CLI, and seamless integration with AI agents through MCP servers and Claude Code skills.

Tokens
257.3K
Snippets
1.1K
Records
1.7K
Agent score
96%

What's inside Bit

  1. Understand the Component Loading Redesign

    master

    Bit is undergoing a multi-phase redesign of its component-loading mechanism to address performance, complexity, and debuggability issues. The redesign aims to move away from 'all-or-nothing' loading and uncoordinated caches toward a staged, lazy loading pipeline with a single environment/aspect load planner.

    Current Status: Phase 1 is shipped; Phase 2 is in progress. Key Goals:

    • Staged Loading: Implementing a lazy loading pipeline to avoid hydrating full components when only partial data (like IDs or dependency lists) is needed.
    • Unified Caching: Reducing the number of uncoordinated caches to a single cache keyed by (id, stage) with a single invalidation event.
    • Decoupling: Detangling environment resolution from component loading and inverting the relationship between legacy ConsumerComponent and Harmony Component.
    • Improved Debuggability: Making cache hits/misses and load errors explicit rather than silent.

  3. What is a Bit component?

    master

    A Bit component is a superset of a Node package. It encapsulates not only the distributable code but also everything required to maintain and develop it as an independent building block, including:

    • Source code
    • Version history
    • Development environment configurations
    • Documentation
    • Tests and compositions

    Components are authored in a Bit workspace, where they are rendered in isolation, compiled, and built. Once 'tagged', a component's release version is stored as an immutable, encapsulated object that can be exported to a Remote Scope (like Bit.dev) to be used by other projects as either a Bit component or a standard Node package.

  5. Manage component scopes with `bit scope`

    master

    Scopes determine where components are stored and published, forming the first part of component IDs. Use the bit scope command to manage scope names and assignments, including setting default scopes and renaming existing ones.

    Key Concepts:

    • Default Scopes: Set in workspace.jsonc.
    • Component Scopes: Default component scopes are set in the .bitmap file. A component is assigned a specific scope (rather than the default) only after it has been versioned.
    • Patterns: You can use patterns to select multiple components. Always wrap patterns in single quotes to prevent shell collisions. Use , to separate patterns and ! to exclude them (e.g., 'ui/*, !ui/button'). Use the $ prefix to filter by states or attributes (e.g., '$deprecated').

  6. Understand Capsules and Networks in Bit

    master

    Bit uses two primary abstractions for isolation:

    • Capsule: A filesystem-based isolated folder containing the component's files and links to the capsules of its dependencies.
    • Network: A collection of capsules related by their dependencies. A network represents a graph of all seed components provided to it along with the full list of associated capsules.
    // Conceptual structure of a Network
const Network = {
  graph: Graph,
  capsules: CapsuleList,
};

  7. Follow CLI design principles for output

    master

    Silence means success

    For commands processing many components (e.g., bit compile, bit import), do not list every successful item by default. Show only failures. If everything passes, show only a summary line. Provide the full list only when the --verbose flag is used.

    Example (All Pass):

    ✔ 309/309 components compiled successfully.
Finished. (45s)

    Example (Some Fail):

       ✖ teambit.workspace/watcher ... failed
   ✖ teambit.vue/vue-aspect ... failed

⚠ 2/309 components failed to compile.
Finished. (45s)

    Reserve checkmarks for summaries

    Use bulletSymbol (›) for individual items in lists. Reserve successSymbol (✔) for summary lines that confirm an operation completed. A long list of checkmarks creates visual noise.

    Section structure

    • Use formatSection for standard patterns: title + optional description + list of items.
    • For non-standard structures (like key-value summaries), use formatTitle for the heading and manually construct the body.

    Joining sections

    Never use compact([...]).join('\n\n'). Always use joinSections([...]), which correctly filters empty strings and joins with double newlines.

    // Standard section
formatSection('modified components', '(use "bit diff" to compare)', items);

// Non-standard section
const title = formatTitle('Merge Summary');
const body = `\nTotal Merged: ${chalk.bold(count)}`;
return `${title}${body}`;

// Error section
const title = `${errorSymbol} ${formatTitle('Installation Error')}`;

// Conflict/warning section
const title = formatTitle(`${warnSymbol} files with conflicts summary`);

  8. How Bit aspects are calculated

    master

    Aspects on a component are determined by merging multiple sources. When a component is loaded, Bit calculates all sources to produce a final list of aspects. Each aspect consists of two parts:

    1. Config: The raw configuration provided by the user.
    2. Data: The processed result generated by the aspect's execution.

    Aspects are resolved from most specific to most general sources.

  9. Understand component loading issues and `bit status`

    master

    Errors that occur during aspect or environment loading (which were previously swallowed) are now surfaced as a new issue type: component-issues (specifically LoadFailure).

    How issues are reported

    • Per-component issues: If an aspect or environment fails to load for a specific component, a LoadFailure issue is attached to that component. This includes the failedId, the phase of failure, and the error itself. These are visible when running bit status.
    • Workspace-level issues: To prevent noise, if a single broken environment or aspect is used by many components, the system aggregates these into a single workspace-level issue. This prevents bit status from being flooded with hundreds of identical entries.

    Impact on workflows

    • Non-blocking: By default, these loading issues are marked as isTagBlocker = false. This means they are visible in bit status to alert you to problems, but they do not prevent operations like bit tag or bit snap from succeeding. They are treated as 'best-effort' loads.
    • Installation context: Errors occurring during mid-install ESM processes (governed by ignoreAspectLoadingError) remain suppressed and do not generate issues.

  10. Avoid All-or-Nothing Component Loading

    master

    By default, methods like workspace.get() and scope.get() perform 'all-or-nothing' loading. This means they eagerly hydrate file contents, resolve dependencies, merge extensions, calculate environments, and execute all onComponentLoad slot handlers (docs, compositions, schema, pkg, preview, dev-files, apps).

    If you only need specific metadata, use partial-load mechanisms to avoid the overhead of full hydration.

    Available Partial-Load Mechanisms:

    • Use ComponentLoadOptions to specify what to load, such as:
      • loadDocs
      • loadCompositions
      • loadSeedersAsAspects
      • idsToNotLoadAsAspects
    • Use workspace.listIds() to retrieve IDs without full component objects.
    • Use graph.getGraphIds() for graph-related operations.

  11. Bit Glossary: Core Terminology

    master

    Understanding Bit requires familiarity with these core concepts:

    • Bit Component: An extensible, portable software container (e.g., UI component, utility, feature, page, or app). Components can depend on other components or packages.
    • Workspace: A Bit-initialized directory containing components.
    • Scope: A collaboration server that defines ownership of components.
    • Application (App): A Bit Component with its own runtime, typically composed of various features and components.
    • Development Environment (Env): A component that bundles development tools like compilers and testers.
    • Lane: A mechanism for managing and releasing modifications (similar to a Git branch).

  12. Understand the difference between `bit start` and `bit start --dev`

    master

    The behavior of the Bit UI depends on how you start the application, which affects which dependencies are required in your node_modules:

    • bit start: Uses pre-built bundles. It does not require heavy UI dependencies (like monaco-editor or date-fns) to be present in the global node_modules because the UI is served from pre-compiled artifacts.
    • bit start --dev: Rebuilds bundles dynamically via webpack. This mode requires full UI dependencies to be installed in node_modules to perform the dynamic rebuilds.