lerna.json

Getting Started with a lerna.json config file

Your folder structure would typically have a packages and a lerna.json config file in the root, so your folder should now look like this:

workspace-repo/
  packages/
    package-a
    package-b
  package.json
  lerna.json

Note We support 3 file extension types (.json, .jsonc and .json5) for Lerna's config, the last 2 can accept comments but only .json and .jsonc support JSON Schema with intellisense in most code editors (like VSCode), so you could in theory add comments to all 3 but .jsonc or .json5 are still preferred to add comments.

How It Works

Lerna-Lite allows you to manage your project using one of two modes: Fixed or Independent.

Fixed/Locked mode (default)

Fixed mode projects operate on a single version line. The version is kept in the lerna.json file at the root of your project under the version key. When you run the Lerna publish command, if a module has been updated since the last time a release was made, it will be updated to the new version you're releasing. This means that you only publish a new version of a package when you need to.

Note: If you have a major version zero, all updates are considered breaking. Because of that, running publish command with a major version zero and choosing any non-prerelease version number will cause new versions to be published for all packages, even if not all packages have changed since the last release.

One issue with this approach is that a major change in any package will result in all packages having a new major version.

Independent mode

"version": "independent" in lerna.json

Independent mode projects allows maintainers to increment package versions independently of each other. Each time you publish, you will get a prompt for each package that has changed to specify if it's a patch, minor, major or custom change.

Independent mode allows you to more specifically update versions for each package and makes sense for a group of components. Combining this mode with something like semantic-release would make it less painful. (There is work on this already at atlassian/lerna-semantic-release).

Set the version key in lerna.json to independent to run in independent mode.

Troubleshooting

If you encounter any issues while using the lib please check out our Troubleshooting document where you might find the answer to your problem.

Frequently asked questions

See FAQ.md.

Concepts

The lib will log to a lerna-debug.log file (same as npm-debug.log) when it encounters an error running a command.

It also has support for scoped packages.

lerna.json

{
  "$schema": "node_modules/@lerna-lite/cli/schemas/lerna-schema.json",
  "version": "1.1.3",
  "command": {
    "publish": {
      "conventionalCommits": true,
      "message": "chore(release): publish new version %v",
      "registry": "https://npm.pkg.github.com"
    }
  },
  "packages": ["packages/*"],
  "useWorkspaces": false,
}

• $schema: JSON Schema to help the developer experience, users can see what properties are valid and a brief description of what they do (taken from the lerna command options documentation)
• version: the current version of the repository.
• npmClient: an option to specify a specific client to run commands with (this can also be specified on a per command basis). Change to "pnpm" or "yarn" to run all commands with configured client. Defaults to "npm".
• npmClientArgs: allows to provide extra arguments to your npmClient,
  • for example "npmClientArgs": ["--production", "--no-optional"]["--production", "--no-optional"]
• command.publish.ignoreChanges: an array of globs that won't be included in lerna changed/publish. Use this to prevent publishing a new version unnecessarily for changes, such as fixing a README.md typo.
• command.publish.message: a custom commit message when performing version updates for publication. See @lerna/version for more details.
• command.publish.registry: use it to set a custom registry url to publish to instead of npmjs.org, you must already be authenticated if required.
• packages: Array of globs to use as package locations.
• useWorkspaces: when this option is enabled, it will get the package locations from the workspaces property from the project root package.json instead of the default packages from lerna.json. This option should only be used with Yarn or the new NPM Workspaces

The packages config in lerna.json (or workspaces when useWorkspaces is enabled) is a list of globs that match directories containing a package.json, which is how the lib recognizes "leaf" packages (vs the "root" package.json, which is intended to manage the dev dependencies and scripts for the entire repo).

By default, the lib initializes the packages list as ["packages/*"], but you can also use another directory such as ["modules/*"], or ["package1", "package2"]. The globs defined are relative to the directory that lerna.json lives in, which is usually the repository root. The only restriction is that you can't directly nest package locations, but this is a restriction shared by "normal" npm packages as well.

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

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

Locating leaf packages under packages/* is considered a "best-practice", but is not a requirement for using this lib.