Bit in Lerna Monorepo

To use Bit in an existing Lerna workspace repository and run:

bit init
Copied

The output should be the following:

successfully initialized a bit workspace.
Copied

You have successfully added Bit support to your Lerna workspace!
See the two generated file; workspace.jsonc, which includes all Bit related configuration, and .bitmap which tracks the Bit components in the workspace. Make sure to add and commit these files to your repository.

You should create a separate directory tree for your Bit components and apps. Open the workspace.jsonc file and add any prefix to the defaultDirectory configuration. For example:

"defaultDirectory": "bit-components/{scope}/{name}",
Copied

Now you need to install and set up the framework plugins you want to utilize. You can use as many plugins as you want, even of they use different stacks or frameworks. Start with installing the plugin:

bit install @bitdev/angular.angular-env
Copied

Now edit your worksapce.jsonc and add the Angular component generator.

{
  "teambit.generator/generator": {
    "envs": ["bitdev.angular/angular-env"]
  }
}
Copied

Note - at this point we recommend reading through the specific documentation for your plugin of choise.

You can decide if you want to use Bit's capabilities for dependency management in a monorepo, or Lerna's.

If you decided to use Lerna for dependency management ensure you do not use bit install in your workflow and you do not have any dependencies in the workspace.jsonc file (if you have any, move them to package.json).

Add the following script to your package.json:

{
  "scripts": {
    "postinstall": "bit import && bit compile && bit link"
  }
}
Copied

Note - the automated dependency detection and definition for components is still supported for Components.

Bit support pnpm and yarn for dependency management and respects configuration applied via package.json. This makes it easy to simply adopt bit install and your dependency management tool.
We recommend moving all dependencies from package.json to workspace.json. You may keep all your scripts and can still run binaries.

Note - if you are using npm now, the only difference for you will feel is pnpm or yarn installing and managing your node_modules.

Now that you have Bit in your Lerna monorepo, you can run any Bit commands to manage components:

bit templates // see all available templates you can use
bit create    // create a new component
bit start     // start the bit local dev-server
bit list      // list all components in the workspace
...
Copied

Similar to Lerna packages, all components are linked to the local node_modules. In you need to use a Bit component in a Lerna package, use the module link:

import { anotherBitComponent } from '@my-org/my-scope/another-bit-component';
Copied

To ensure the compiled outputs of components is up-to-date in node_modules, you need to run one of the following processes:

bit watch // runs component-compilation in a watch mode, ensure compiled node-modules for components are up-to-date
bit start // runs bit-devserver which also ensures compiled node-modules for components are up-to-date
Copied

It is possible to import a local Lerna package by a Bit component. However, you need to ensure the Lerna package is also published to a registry, so when other consumers install the Bit component, they will get the Lerna package as a dependency.

With Bit you can create additional apps in your Lerna monorepo.
To create a new app, simply choose the *-app template when creating a new component:

bit create ng-app apps/my-angular-app
Copied

Then add it to your workspace.jsonc configuration with the bit use command:

bit use apps/my-angular-app
Copied

Now you can use the following application-workflow commands:

bit app list    // lists all available Bit apps in the repotisory
bit run <name> // runs a Bit app in a seperate dev-server, alongside your app
Copied

Note - You can run any type of App you want, not just Angular. To do so, you just need to add the specific framework plugin to your workspace.jsonc file, similar to how you added bitdev.angular/anguler-env.

As you probably have a working and custom delivery pipeline, it is hard to provide a simple way to integrate Bit release pipeline that "will just work". Please use the following as a reference for incorporating Bit scripts in your pipeline:

• When new PR is submitted
  • Developers should run bit tag --soft on their local to mark the modified components to be versioned and released. This modifies .bitmap with updates for components. You can review these changes as part of the PR flow.
  • On CI add the bit build command to run isolated build pipeline for all modified components.
• When PR is merged
  • Add bit tag --persist && bit export to apply changes in .bitmap on the components and release them.
  • Add a "commit back" to the changes in .bitmap file and re-push it to the repository

You can also build a more advanced flow using the Bit's pre-made CI scripts, as reference.

• When new PR is submitted
  • On CI add the bit lane create && bit snap && bit export command to run isolated build pipeline for all modified components and publish a new lane with all component-changes.
• When PR is updates
  • On CI add the bit snap && bit export to update the modified components.
• When PR is merged
  • Add bit tag && bit export to release new versions for the components.
  • Add a "commit back" to the changes in .bitmap file and re-push it to the repository