@lerna/bootstrap

What is @lerna/bootstrap?

@lerna/bootstrap is a part of the Lerna monorepo management toolset. It is used to install and link dependencies for a multi-package repository, ensuring that all inter-package dependencies are properly resolved and symlinked.

What are @lerna/bootstrap's main functionalities?

Install dependencies

This feature installs all the dependencies for the packages in the monorepo. It uses the npm client and hoists common dependencies to the root node_modules directory.

const { bootstrap } = require('@lerna/bootstrap');

bootstrap({
  cwd: process.cwd(),
  npmClient: 'npm',
  hoist: true
}).then(() => {
  console.log('Dependencies installed and linked');
});

Link local packages

This feature links local packages together, ensuring that inter-package dependencies are resolved using symlinks. This is useful for development as changes in one package are immediately reflected in dependent packages.

const { bootstrap } = require('@lerna/bootstrap');

bootstrap({
  cwd: process.cwd(),
  npmClient: 'npm',
  hoist: true
}).then(() => {
  console.log('Local packages linked');
});

Run lifecycle scripts

This feature runs specified lifecycle scripts (e.g., prepublish, postinstall) for all packages in the monorepo. This ensures that any necessary build steps or other setup tasks are performed.

const { bootstrap } = require('@lerna/bootstrap');

bootstrap({
  cwd: process.cwd(),
  npmClient: 'npm',
  hoist: true,
  scripts: ['prepublish', 'postinstall']
}).then(() => {
  console.log('Lifecycle scripts executed');
});

Other packages similar to @lerna/bootstrap

yarn

Yarn is a package manager that also supports monorepos through its workspaces feature. It installs dependencies and links local packages similarly to @lerna/bootstrap, but it is a more general-purpose tool with a broader scope.

pnpm

pnpm is a fast, disk space-efficient package manager that also supports monorepos. It uses a content-addressable file system to store all files from all module directories on a disk. It is similar to @lerna/bootstrap in that it can install and link dependencies, but it offers additional performance benefits.

rush

Rush is a monorepo management tool that provides sophisticated support for managing large repositories with many packages. It includes features for installing dependencies, linking local packages, and running lifecycle scripts, similar to @lerna/bootstrap, but it also offers advanced features like incremental builds and change tracking.

README

@lerna/bootstrap

Link local packages together and install remaining package dependencies

Install lerna for access to the lerna CLI.

Usage

$ lerna bootstrap

Bootstrap the packages in the current Lerna repo. Installs all of their dependencies and links any cross-dependencies.

When run, this command will:

1. npm install all external dependencies of each package.
2. Symlink together all Lerna packages that are dependencies of each other.
3. npm run prepublish in all bootstrapped packages (unless --ignore-prepublish is passed).
4. npm run prepare in all bootstrapped packages.

lerna bootstrap accepts all filter flags.

Pass extra arguments to npm client by placing them after --:

$ lerna bootstrap -- --production --no-optional

May also be configured in lerna.json:

{
  ...
  "npmClient": "yarn",
  "npmClientArgs": ["--production", "--no-optional"]
}

--hoist [glob]

Install external dependencies matching glob at the repo root so they're available to all packages. Any binaries from these dependencies will be linked into dependent package node_modules/.bin/ directories so they're available for npm scripts. If the option is present but no glob is given the default is ** (hoist everything). This option only affects the bootstrap command.

$ lerna bootstrap --hoist

For background on --hoist, see the hoist documentation.

Note: If packages depend on different versions of an external dependency, the most commonly used version will be hoisted, and a warning will be emitted.

Note: --hoist is incompatible with file: specifiers. Use one or the other.

Note: --hoist no longer accepts multiple string values since v3.18.0. Use the following instead:

a. Wrap string values by quotes:

$ lerna bootstrap --hoist "{rollup,postcss-cli,webpack-cli,babel-loader,npm-run-all}"

b. Specify the list of values in lerna.json:

{
  "command": {
    "bootstrap": {
      "hoist": [
        "rollup",
        "postcss-cli",
        "webpack-cli",
        "babel-loader",
        "npm-run-all"
      ]
    }
  },
  ...
}

--strict

When used in conjunction with hoist will throw an error and stop bootstrapping after emitting the version warnings. Has no effect if you aren't hoisting, or if there are no version warnings.

$ lerna bootstrap --hoist --strict

--nohoist [glob]

Do not install external dependencies matching glob at the repo root. This can be used to opt out of hoisting for certain dependencies.

$ lerna bootstrap --hoist --nohoist=babel-*

--ignore

$ lerna bootstrap --ignore component-*

The --ignore flag, when used with the bootstrap command, can also be set in lerna.json under the command.bootstrap.ignore key. The command-line flag will take precedence over this option.

Example

{
  "version": "0.0.0",
  "command": {
    "bootstrap": {
      "ignore": "component-*"
    }
  }
}

Hint: The glob is matched against the package name defined in package.json, not the directory name the package lives in.

Options

--ignore-prepublish

Skip prepublish lifecycle scripts run by default in bootstrapped packages. Note, this lifecycle is deprecated, and will likely be removed in the next major version of Lerna.

$ lerna bootstrap --ignore-prepublish

--ignore-scripts

Skip any lifecycle scripts normally run (prepare, etc) in bootstrapped packages.

$ lerna bootstrap --ignore-scripts

--registry <url>

When run with this flag, forwarded npm commands will use the specified registry for your package(s).

This is useful if you do not want to explicitly set up your registry configuration in all of your package.json files individually when e.g. using private registries.

--npm-client <client>

Must be an executable that knows how to install npm package dependencies. The default --npm-client is npm.

$ lerna bootstrap --npm-client=yarn

May also be configured in lerna.json:

{
  ...
  "npmClient": "yarn"
}

--use-workspaces

Enables integration with Yarn Workspaces (available since yarn@0.27+). The values in the array are the commands in which Lerna will delegate operation to Yarn (currently only bootstrapping). If --use-workspaces is true then packages will be overridden by the value from package.json/workspaces., and both --ignore and --scope will be ignored. May also be configured in lerna.json:

{
  ...
  "npmClient": "yarn",
  "useWorkspaces": true
}

The root-level package.json must also include a workspaces array:

{
  "private": true,
  "devDependencies": {
    "lerna": "^2.2.0"
  },
  "workspaces": ["packages/*"]
}

This list is broadly similar to lerna's packages config (a list of globs matching directories with a package.json), except it does not support recursive globs ("**", a.k.a. "globstars").

--no-ci

When using the default --npm-client, lerna bootstrap will call npm ci instead of npm install in CI environments. To disable this behavior, pass --no-ci:

$ lerna bootstrap --no-ci

To force it during a local install (where it is not automatically enabled), pass --ci:

$ lerna bootstrap --ci

This can be useful for "clean" re-installs, or initial installations after fresh cloning.

--force-local

$ lerna bootstrap --force-local

When passed, this flag causes the bootstrap command to always symlink local dependencies regardless of matching version range.

publishConfig.directory

This non-standard field allows you to customize the symlinked subdirectory that will be the source directory of the symlink, just like how the published package would be consumed.

  "publishConfig": {
    "directory": "dist"
  }

In this example, when this package is bootstrapped and linked, the dist directory will be the source directory (e.g. package-1/dist => node_modules/package-1).

How It Works

Let's use babel as an example.

• babel-generator and source-map (among others) are dependencies of babel-core.
• babel-core's package.json lists both these packages as keys in dependencies, as shown below.

// babel-core package.json
{
  "name": "babel-core",
  ...
  "dependencies": {
    ...
    "babel-generator": "^6.9.0",
    ...
    "source-map": "^0.5.0"
  }
}

• Lerna checks if each dependency is also part of the Lerna repo.
  • In this example, babel-generator can be an internal dependency, while source-map is always an external dependency.
  • The version of babel-generator in the package.json of babel-core is satisfied by packages/babel-generator, passing for an internal dependency.
  • source-map is npm installed (or yarned) like normal.
• packages/babel-core/node_modules/babel-generator symlinks to packages/babel-generator
• This allows nested directory imports

Notes

• When a dependency version in a package is not satisfied by a package of the same name in the repo, it will be npm installed (or yarned) like normal.
• Dist-tags, like latest, do not satisfy semver ranges.
• Circular dependencies result in circular symlinks which may impact your editor/IDE.

Webstorm locks up when circular symlinks are present. To prevent this, add node_modules to the list of ignored files and folders in Preferences | Editor | File Types | Ignored files and folders.

Changelog

6.0.2 (2022-11-02)

Bug Fixes

• publish: remove workspace prefix on publish (#3397) (1f0e546)