Migrate to New Component Development Environments

itaysso3 months ago

Bit Envs (component development envs) allow you to define tooling, configuration and operations for your components. Starting from version 0.1.0 Bit simplifies the implementation for envs, allowing you for more control and flexibility.

In this blog post, I will highlight the differences between the revised env structure and how it was before, so you can have a solid model for successfully moving from your current implementation to the new one.

In a Nutshell...

There are five major upgrades to your developer experience as you move to the new envs API:

  • All envs are now decoupled from Bit and have independent versions.
  • Configuration files for tools are right there for you to modify.
  • Defaults and configurations from Bit are easy to opt out.
  • Up-to-date tooling and configurations.
  • ESM support everywhere.

The bottom line is - you get more visibility into what the env does, it is easier for you to modify your tooling, and you get more stability.

To effectively upgrade, you can choose one of two paths:

  • Create a new Bit env with the configuration you want, and use bit env replace to gradually update your Bit Components' configuration.
  • Completely refactor the current Bit env implementation you have with an updated one, and use bit env update to promote Bit env version for your components.

Let's go over the first option, as it provides a more direct and easy way to experiment and revert changes.

Create a New Bit Env

Depending on the framework and workflow at hand, consult the documentation to understand how to create a new Bit env that fits your tech stack. Here, I'll be using React as a base.

Use Templates

Generate a new env using a template:


Copy the generated component ID of the env, and replace your newly-created env in the workspace.jsonc as follows:

"teambit.generator/generator": { 
  "envs": [ "my-org.my-scope/envs/my-react-env" ]

Run the following command to install all required plugins for your env (head over to the docs to learn about each of them):


Tip - bit status command help you validate if all plugins are installed correctly.

Replace Current Env with a New One

Now that you have a new Bit env, it's time to update the configuration of components. Use the bit env replace command, as follows:


Once your env has been replaced, I'd recommend deleting the compiled outputs of your components and rerun compilation:

rm -rf node_modules/@your-org
bit link && bit compile

The components will now use the new envs, and the last step is to migrate all customizations made in the current env. More information can be found in the documentation of the env being used.

Customization TL;DR and FAQ

There are some key differences in how envs are operated, which will impact the migration of customization work done in the old Bit envs. The base configuration is kept similar between envs, but there are some changes to understand:

Changes in Defaults

For the most part we kept the same base configuration similar between envs. But there are some changes to understand:

  • React - Base React version is 18, compilation target is now ESM (previously CJS) and Jest updated to 29.X.
  • Node - Compilation target is now ESM (previously CJS) and Jest updated to 29.X.
  • Lit - Compilation target is now ESM (previously CJS) and Jest updated to 29.X.
  • Angular - No changes in defaults, as they fit the current baseline from Angular.

Tooling Configurations

Instead of using APIs and transformers, users now have complete access to configuration files for all underline tools in a single directory as part of the env.

├── eslintrc.js
├── jest.config.ts
├── prettier.config.ts
└── tsconfig.json

Each tool refers to the base configurations coming from Bit.

Apply Theme on Compositions

When you need to ensure all your component-compositions are "wrapped" by a single theme or any other provider head to the preview/mounter.* file of your component. There you find a dedicated function to wrap any of your compositions with custom code.

Dependency Definitions

Align versions for dependencies, or setting certain deps to be peerDependencies for components is now control from a simple env.jsonc configuration file.