Scoped component indexes enable organizations to manage design system components centrally and share them across multiple projects and teams. Instead of recreating component indexes for each application, teams can now define component libraries once and reuse them organization-wide with proper governance and versioning.
Component index scopes determine the visibility and accessibility of your indexed design system components:
- Space scope: components are only available within the specific Builder Space where they were indexed.
- Organization scope: components are shared across all Spaces within your Builder Organization.
- Global scope: components are available to all of your Builder users (reserved for open-source libraries and Builder-managed content).
- First, have a component index available or create one following the instructions in Component indexing.
- Go to the Design System Intelligence page to change the scope.
- Choose the scope carefully as it determines who can access your component library
- The design system name must be unique within the selected scope
- Organization and global scopes require appropriate permissions
Configure your project to use scoped component libraries by referencing them in your builder.config.json:
{
"workspace": {
"componentIndexes": [
"design-system-1.0.0",
"material-ui-components-2.1.0",
"custom-app-components-1.2.0"
]
}
}This configuration allows your project to access multiple component libraries simultaneously. You can reference component libraries with different scopes in the same project, as long as you have access to them.
To find out which version of a component library your project is currently using, check the component library names listed in your builder.config.json file.
To access your component index scopes:
- In your Builder Space, go to Design System Intelligence.
- The list of available component indexes with their scope is displayed.
Changing the scope from Organization to Space restricts access for other Spaces that were previously using a given design system. Teams in other Spaces lose access to these components and cannot use them during code generation.
When you change a component index's scope, the component indexes themselves remain unchanged. Only the visibility and access permissions are affected.
To modify a component index scope:
- Go to Design System Intelligence.
- Click the three dots and choose Change Scope.
- Select the new scope.
- Click the Confirm button.
The video below shows where to change the scope:
The ability to modify a component index's scope depends on your role within the organization:
| Action | Member | Organization Admin | Builder.io Admin |
|---|---|---|---|
Modify scope to Organization | ❌ | ✅ | ✅ |
Modify scope to Organization | ❌ | ❌ | ✅ |
When managing scoped component indexes, you might encounter these common issues. Below are the causes and solutions:
Component library name conflicts
Error message: "A design system with this name already exists in the selected scope."
Solution: Design system names must be unique within their scope; that is, Space, Organization, or Global. Choose a different name.
Missing components after scope change
Issue: Components are no longer available after changing scope from Organization to Space.
Solution: This is expected behavior. Other Spaces in your organization no longer have access to the component library. You may need to do one of the following:
- Revert the scope change.
- Provide alternative component libraries to affected Spaces.
Deleting component libraries in use
Issue: You want to delete a component library that other projects might be using.
Solution: Builder will display a warning message, but allows deletion even if other projects are using the component index. Coordinate with affected teams before proceeding to avoid breaking their builds.
These best practices will help you maintain organized, secure, and scalable component libraries across your organization
Design system management
- Use Organization scope for shared design systems that multiple teams use.
- Use Space scope for application-specific components that shouldn't be shared.
- Establish naming conventions that include version numbers and clear descriptions.
- Document component changes when updating libraries that other teams depend on.
Permissions management
- Principle of least privilege. Only grant Organization-scope permissions to team members who need them.
- Regular audits. Periodically review who has access to create and modify Organization-scoped libraries.
- Documentation. Maintain documentation about who owns which component libraries
Component indexes created before scoped indexing was available were automatically assigned Space scope. If you want to share these across your organization, you can change them to Organization scope:
- Go to Design System Intelligence.
- Find your existing component library
- Change the scope from Space to Organization Note that this requires Organization admin permissions.
- Update your project's
builder.config.jsonto reference the newly scoped libraries:
{
"workspace": {
"componentIndexes": [
"legacy-design-system-1.0.0", // Now organization-scoped
"new-shared-components-2.0.0" // New organization-scoped library
]
}
}
For additional help with scoped component indexes:
- Learn the basics of Component Indexing if you haven't already.
- Contact your Organization administrator for permission-related issues.
- Reach out to support@builder.io.