Skip to main content

Scoping Components

Scope components according to their business concerns as well as a remote place to store components and enable better component discoverability.

Component Scope#

A component's scope describes its business concern. Good scope names are descriptive.
We recommend names to be specific to the topic handled by components:

  • base-ui - all basic UI elements and components for building web-ui.
  • inventory - set of components relevant for inventory management in an e-commerce app.
  • authentication - components for managing user authentication and tokens.
Component Scope and Target Remote

Component Scope name is used to determine the target remote Bit scope for exporting components. When defining scopes for components it's important to also create remote scopes of the same names. Lean more

Set Component Scope#

Component's scope is defined as part of your workspace configuration. Set a default scope for all components by configuring the teambit.workspace/workspace aspect's defaultScope property:

{  "teambit.workspace/workspace": {    "name": "ACME's Inventory Workspace",    "defaultScope": "acme.inventory"  },

A single workspace can export components to multiple scopes. To achieve that, use @teambit.workspace/variants aspect.

{  "teambit.workspace/variants": {    "...": {      "defaultScope": "acme.authentication"    },    "...": {      "defaultScope": "acme.base-ui"    },  }}
Scope owners in Bit.dev

Scopes hosted on Bit.dev should be prefixed by their owner account and use a . as a separator. This is so different organizations on the platform can create similarly named scopes of their own. For example:

  • acme.base-ui
  • acme.inventory
  • acme.authentication

See Component Scope#

There are several options to ensure component scope is set correctly:

  1. Run bit start and explore the component tree. The top-most level items are scopes.
  2. bit show <component> to see all information on a component, including scope name.
  3. bit env shows a table of all components and their applied environment config, including scope name.

Component Module Name#

Scope is the prefix for component IDs. Everything that comes before the first / is the component's scope.

checkout/ui/purchase-summary

In this example:

  • checkout - scope.
  • ui - namespace inside the scope.
  • purchase-summary - component name.

When translating this to a component module name (for import {...} from ....) Bit does the following:

  • The acme part of the component ID translates to an npm scope.
  • As npm only supports 1 level of nesting components, all / becomes ..
module name for component
@checkout/ui.purchase-summary
Scopes with the . separator

If your scope name has . as a separator (similar to scopes on Bit.dev) Bit splits it to two, and takes the first part ({owner}) and sets it as the npm scope. The second part becomes the namespace.

Module name with {owner}
acme.checkout/ui/purchase-summary => @acme/checkout.ui.purchase-summary

Component Scope and Workspace Structure#

Bit's default behavior for structuring a workspace is to sort components in directories according to their respected scopes. This is to make the workspace easier to navigate by creating symmetry between the logical structure of components and their physical location.

When creating new components you can define the component's scope with the following syntax:

bit create react-component ui/purchase-summary --scope checkout

Bit will create the component in the following directory:

.└── checkout    └── ui        └── purchase-summary