Managing JavaScript projects with Lerna (with examples)

Lerna is a powerful tool for managing JavaScript projects with multiple packages. It simplifies the development workflow by providing a set of commands for initializing projects, installing dependencies, running scripts, executing shell commands, and publishing packages. In this article, we will explore different use cases of the lerna command and provide examples for each use case.

1: Initializing project files

To initialize project files such as lerna.json, package.json, .git, etc., you can use the lerna init command. This command sets up the basic structure of your project and creates the necessary configuration files.

lerna init

Motivation: This command is useful when starting a new project with Lerna. It automatically creates the required files and sets up the project structure, saving you time and effort.

Explanation: The lerna init command creates a new Lerna project by creating the lerna.json configuration file and other project files. It also initializes a Git repository if one doesn’t already exist.

Example output:

lerna notice cli v4.0.0
lerna info versioning independent
lerna info Initializing Git repository
lerna info Wrote Lerna config lerna.json
lerna success Initialized Lerna files

2: Installing dependencies and symlinking local dependencies

When working with multiple packages in a Lerna project, it is essential to manage dependencies efficiently. The lerna bootstrap command installs all external dependencies of each package and symlinks together local dependencies.

lerna bootstrap

Motivation: This command is useful when setting up a project that has multiple packages. It ensures that all packages have their dependencies installed and linked correctly, enabling seamless development and testing.

Explanation: The lerna bootstrap command performs the following tasks:

• It installs external dependencies using the package manager specified in the lerna.json file (e.g., npm or Yarn).
• It resolves local dependencies by creating symlinks between packages within the project.

Example output:

lerna info Bootstrapping 2 packages
lerna info Symlinking packages and binaries
lerna success Bootstrapped 2 packages

3: Running a script for every package

Lerna provides the lerna run command to run a specific script for every package that contains it in its package.json file. This is useful when you have scripts that need to be executed across multiple packages, such as running tests or building all packages.

lerna run script

Motivation: Running a script across multiple packages can be tedious and error-prone. With the lerna run command, you can easily execute a script in every package that has it defined, saving time and effort.

Explanation: The lerna run command executes the specified script for each package that contains it in its package.json file. The script argument should be the name of the script defined in the scripts section of the package’s package.json file.

Example output:

lerna info Executing command in 2 packages: "npm run test"
lerna success run Ran npm script 'test' in 2 packages in 0.2s:
lerna success - package-1
lerna success - package-2

4: Executing an arbitrary shell command in every package

Apart from running scripts, Lerna allows you to execute arbitrary shell commands in every package using the lerna exec command. This is useful when you need to perform custom operations across multiple packages, such as creating build artifacts.

lerna exec -- ls

Motivation: In some cases, you may need to execute shell commands directly instead of relying on package scripts. The lerna exec command allows you to run any shell command in each package, giving you flexibility and control over your project.

Explanation: The lerna exec command executes the specified shell command in every package. The ls command in the example lists the files and directories in each package’s root directory.

Example output:

lerna info Executing command in 2 packages: "ls"
lerna success exec Executed command 'ls' in 2 packages in 0.2s:
lerna success - package-1:
file-1.txt
file-2.txt

lerna success - package-2:
file-3.js
file-4.js

5: Publishing packages that have changed since the last release

Publishing packages in a Lerna project is made easy with the lerna publish command. It identifies packages that have changed since the last release and publishes them to the specified package registry (e.g., npm).

lerna publish

Motivation: When you have multiple packages in your project, it can be time-consuming to manually track which packages need to be published. The lerna publish command automates this process by identifying changes and publishing only the affected packages.

Explanation: The lerna publish command performs the following tasks:

• It identifies packages that have changed by comparing the Git history with the last released version.
• It prompts you to select the new version for each changed package.
• It publishes the selected packages to the specified registry, taking care of versioning and publishing process.

Example output:

lerna info Looking for changed packages since v1.0.0
lerna info Filtering out packages that do not have any changes
lerna info Preparing to publish packages: package-1, package-2
lerna info Confirm: Are you sure you want to publish the above changes? (yes) yes
lerna info Checking git status...
lerna info Publishing packages to npm...
lerna info Published package-1@1.1.0
lerna info Published package-2@2.0.0
lerna success Published packages: package-1@1.1.0, package-2@2.0.0

Conclusion

In this article, we explored different use cases of the lerna command, a tool for managing JavaScript projects with multiple packages. We covered initializing project files, installing dependencies, running scripts, executing shell commands, and publishing packages. These commands are essential for streamlining the development workflow and improving project management in Lerna projects.