Lerna basic concepts

Introduction

Recently, I have to get in touch with relevant things at work, and I have begun to familiarize myself with the documents and make relevant translation records for easy reference later.

Based on Lerna version: v3.22.1.

Lerna is a tool for managing JavaScript projects with multiple packages.

• Origin
• My GitHub

about

Dividing a large code base into independent versions of packages is very useful for code sharing. However, making changes in many repositories can become messy and difficult to track, and cross-repository testing can quickly become complicated.

To solve these (and many other) problems, some projects will organize their code bases into multiple package repositories (sometimes called monorepos ). Like Babel , React , Angular , Ember , Meteor , Jest and many other packages were developed in the development of a package library.

Lerna is a tool to optimize the workflow of managing multi-package repositories through git and npm.

Lerna can also reduce the need for time and space for many package copies in the development and build environment. Usually, the download of a project is divided into many independent NPM packages. See the hoist document for details.

What does a Lerna library look like?

Actually nothing. A file system similar to the following:

my-lerna-repo/
  package.json
  packages/
    package-1/
      package.json
    package-2/
      package.json

What can Lerna do?

The two basic commands of Lerna are: lerna bootstrap and lerna publish .

• bootstrap will link the dependencies in the library.
• publish will release any updated packages.

What can't Lerna do?

Lerna is not a deployment tool for 16108952161611 Hoisting may not be compatible with traditional 16108952161617

Start

The following description applies to the 3.x version of Lerna. For a new project, we recommend using this version instead of version 2.x.

Let's start by installing Lerna via npm as a dev dependency of your project.

$ mkdir lerna-repo && cd $_
$ npx lerna init

This will create a lerna.json configuration file and a package folder, so your folder should now look like this:

lerna-repo/
  packages/
  package.json
  lerna.json

How it works

Lerna allows you to manage projects in one of two modes: Fixed or Independent .

Fixed/Locked mode (default)

For the Lerna project in Fixed mode, its operation is on a version line. This version is stored in lerna.json file version on the property, this file is in the root directory of your project. When you run lerna publish , if a module has been updated since the last release, it will be updated to a new version you released. This means releasing a new version of a package when you need it.

Note: If you have a 0 major version (for example 0.yz), all updates to are considered destructive . Because of this, running lerna publish with 0 major version and selecting any non-pre-release version number will cause all packages to release new versions, even though not all packages have changed since the last release.

This is the mode currently used by Babel If you want to automatically group all package versions together, use this mode. One problem with this model is that major changes to any package will cause all packages to have corresponding new versions.

Independent mode

lerna init --independent

The Lerna project in Independent mode allows maintainers to upgrade the respective version of each package. Every time you release, you will be prompted for each changed package to specify whether it is a patch, minor, major, or custom change.

Independent mode allows you to specifically update the version of each package, which is very helpful for a group of components. This mode combined with something like semantic-release will reduce a lot of trouble. ( atlassian/lerna-semantic-release already doing this).

When running in independent mode, you need to set the value of the version field in the lerna.json file to independent.

Solved problem

If you have any problems when using Lerna, please document there may be the answer you want.

common problem

See FAQ.md .

concept

When Lerna runs to trigger an error, it will generate a lerna-debug.log file (same as the npm-debug.log

Lerna also supports scoped packages .

Run lerna --help to see all available commands and options.

lerna.json

{
  "version": "1.1.3",
  "npmClient": "npm",
  "command": {
    "publish": {
      "ignoreChanges": ["ignored-file", "*.md"]
    },
    "bootstrap": {
      "ignore": "component-*",
      "npmClientArgs": ["--no-package-lock"]
    }
  },
  "packages": ["packages/*"]
}

• version : The version of the current library.
• npmClient : Specify options for specific clients to run commands (you can also specify them for each command). If you want to use yarn to run all commands, change this value to "yarn" . The default is "npm".
• command.publish.ignoreChanges : Global array, the changes to the specified file will not be included in lerna changed/publish . This is used to prevent some unnecessary changes from being released, such as the modification README.md .
• command.publish.message : Customize the submission information when the version is released. For more information, see @lerna/version .
• command.publish.registry : Use this setting to automatically publish sources. If authentication is required, authentication must be performed first.
• command.bootstrap.ignore : Global array, the specified content in it will not be associated lerna bootstrap
• command.bootstrap.npmClientArgs : A global array lerna bootstrap command is run, it is directly passed to the parameters of the npm install
• command.bootstrap.scope : A global array used to limit which packages will be booted when the lerna bootstrap
• packages : The global array used as the location of the package.

The configuration of the package in lerna.json package.json file. This is how lerna organizes "leaf" packages (relatively, the "root" package.json is to manage the dev dependencies and scripts of the entire library) .

By default, the lerna initialization package list is ["packages/*"] , but you can also use another directory such as ["modules/*"] , or ["package1", "package2"] . The global definition is relative to lerna.json file is located, usually the root directory of the library. The only restriction is that you cannot directly nest the package location, which is also a restriction common to "standard" npm packages.

For example, ["packages/*", "src/**"] matches this tree structure:

packages/
├── foo-pkg
│   └── package.json
├── bar-pkg
│   └── package.json
├── baz-pkg
│   └── package.json
└── qux-pkg
    └── package.json
src/
├── admin
│   ├── my-app
│   │   └── package.json
│   ├── stuff
│   │   └── package.json
│   └── things
│       └── package.json
├── profile
│   └── more-things
│       └── package.json
├── property
│   ├── more-stuff
│   │   └── package.json
│   └── other-things
│       └── package.json
└── upload
    └── other-stuff
        └── package.json

Putting leaf packs under packages/* is considered a best practice, but it is not a requirement for using Lerna.

Deprecated fields

lerna.json are no longer supported, including:

• lerna : It was used to specify the current version of Lerna, which has been deprecated and deleted in V3.

Public devDependencies

Most devDependencies can be placed at the root of Lerna library lerna link convert

The above command will automatically promote and use the file: specifier.

The promotion has the following benefits:

• All packages use the same version provided with dependencies.
• You can use automated tools to keep the root dependencies up to date, such as GreenKeeper .
• The time to install dependencies is reduced.
• Reduce the occupied storage space.

devDependencies , which provides "binary" executable files used by npm scripts, still needs to be installed directly in each package that uses them.

For example, nsp is a necessary dependency when lerna run nsp

{
  "scripts": {
    "nsp": "nsp"
  },
  "devDependencies": {
    "nsp": "^2.3.3"
  }
}

Git boost dependency

Lerna can specify the locally dependent version by adding 06108952161d52 (such as #v1.0.0 or #semver:^1.0.0 git remote url , committish When the package must be private and does not require the private npm registry , it is allowed to distribute the package through the Git repository. (For detailed information about the implementation, refer to this description )

Please note that Lerna does not actually split git history into separate read-only repositories. This is the responsibility of the user.

// packages/pkg-1/package.json
{
  name: "pkg-1",
  version: "1.0.0",
  dependencies: {
    "pkg-2": "github:example-user/pkg-2#v1.0.0"
  }
}

// packages/pkg-2/package.json
{
  name: "pkg-2",
  version: "1.0.0"
}

In the example above:

• lerna bootstrap command will correct the pkg-2 link to pkg-1 in.
• When pkg-2 changes, the lerna publish command will update the #v1.0.0 (06108952161de8) to pkg-1 .

README Badge

Use Lerna? Add a README Badge to show it:

[![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/)

Guide

If you prefer the command-line boot method, you may like lerna-wizard . It will guide you through a series of defined steps:

Reference

• lerna github