What is @lerna/import?
@lerna/import is a tool that helps you import packages into a Lerna-managed monorepo. It simplifies the process of migrating existing packages into a monorepo structure, ensuring that dependencies and configurations are correctly handled.
What are @lerna/import's main functionalities?
Importing a package
This command imports an existing package into the Lerna monorepo. The <path-to-package> should be the path to the package you want to import. Lerna will handle the necessary adjustments to integrate the package into the monorepo.
npx lerna import <path-to-package>
Handling Git history
This command imports a package while preserving its Git commit history. This is useful for maintaining the development history of the package within the monorepo.
npx lerna import <path-to-package> --preserve-commit
Customizing import path
This command allows you to specify a custom destination path within the monorepo for the imported package. The --dest option lets you define where the package should be placed.
npx lerna import <path-to-package> --dest=packages/custom-path
Other packages similar to @lerna/import
lerna
Lerna itself is a tool for managing JavaScript projects with multiple packages. While @lerna/import is a specific command within Lerna for importing packages, Lerna provides a broader set of functionalities for managing monorepos, including versioning, publishing, and dependency management.
yarn
Yarn is a package manager that also supports workspaces, which can be used to manage monorepos. Yarn workspaces allow you to set up multiple packages within a single repository, similar to Lerna, but it does not have a specific import command like @lerna/import.
pnpm
pnpm is another package manager that supports monorepos through its workspace feature. It offers efficient package management and disk space usage. While it does not have a direct import command, it provides similar functionalities for managing multiple packages in a monorepo.
lerna import
Import a package into the monorepo with commit history
Install lerna for access to the lerna
CLI.
Usage
$ lerna import <path-to-external-repository>
Import the package at <path-to-external-repository>
, with commit history,
into packages/<directory-name>
. Original commit authors, dates and messages
are preserved. Commits are applied to the current branch.
This is useful for gathering pre-existing standalone packages into a Lerna
repo. Each commit is modified to make changes relative to the package
directory. So, for example, the commit that added package.json
will
instead add packages/<directory-name>/package.json
.
Note: If you're importing an external repository on a new lerna repository, then do remember to have at least one commit.
$ git init lerna-repo && cd lerna-repo
$ npx lerna init
$ npm install
$ git add .
$ git commit -m "Initial lerna commit"
$ npx lerna import <path-to-external-repository>
Options
--flatten
When importing repositories with merge commits with conflicts, the import command will fail trying to apply all commits. The user can use this flag to ask for import of "flat" history, i.e. with each merge commit as a single change the merge introduced.
$ lerna import ~/Product --flatten
--dest
When importing repositories, you can specify the destination directory by the directory listed in lerna.json.
$ lerna import ~/Product --dest=utilities
--preserve-commit
Each git commit has an author and a committer (with a separate date for each). Usually they're the same person (and date), but since lerna import
re-creates each commit from the external repository, the committer becomes the current git user (and date). This is technically correct, but may be undesirable, for example, on Github, which displays both the author and committer if they're different people, leading to potentially confusing history/blames on imported commits.
Enabling this option preserves the original committer (and commit date) to avoid such issues.
$ lerna import ~/Product --preserve-commit