Migrating from Yarn guide

Convert a Yarn Classic or Berry yarn.lock project to LPM CLI with rollback safety.

lpm migrate converts a Yarn Classic or Yarn Berry project to LPM CLI. It writes a version 12 staging lockfile.

By default, an online install then writes version 13 with exact package-instance identities.

This guide covers the Yarn-specific parts. For the full flag reference, see lpm migrate.

Prerequisites

LPM CLI installed - see Installation.
A package.json and yarn.lock in the project root.
A clean or committed working tree.

Run the dry-run first and treat it as the source of truth for what will convert.

1. Preview

lpm migrate --dry-run

Dry-run detects Yarn, parses yarn.lock, converts the graph in memory, and writes nothing. It reports package counts, workspace counts, and any conversion problems before touching disk.

If the project contains multiple lockfiles, LPM CLI chooses the most recently modified one. On timestamp ties, the priority order is bun.lockb, bun.lock, pnpm-lock.yaml, yarn.lock, then package-lock.json. Remove stale lockfiles before migrating so yarn.lock is the unambiguous source.

2. Run The Migration

lpm migrate

What runs:

Confirm package.json exists and refuse to overwrite an existing lpm.lock unless --force is set.
Parse Yarn lockfile entries: Classic specifier blocks or Berry descriptor entries, exact versions, and dependency edges.
Preserve Classic resolved tarball URLs and SRI integrity strings. Berry cache checksums are not npm SRI strings, so they are not written as integrity.
Mark direct dev and optional dependencies from root package.json, because Yarn does not encode those flags in a way LPM CLI can carry over per lockfile entry.
Write a version 12 staging lpm.lock. If the graph fits the binary format, write lpm.lockb.
Back up yarn.lock, .npmrc when touched, .gitattributes, and any pre-existing LPM CLI lockfiles.
Add LPM CLI registry routing to .npmrc unless --no-npmrc is set.
If --no-install is not set, run an online lpm install. This step writes version 13 and removes the staging binary file.
Run build + test scripts unless --skip-verify is set.

The flow is non-interactive. -y is accepted but reserved for a future interactive mode; it does not imply --force.

3. Verify

If you used --no-install, run lpm install before the offline command.

lpm install --offline
lpm test
lpm lint

lpm install --offline confirms the new lockfile and the warmed store can replay without network access. If your project does not have test or lint scripts, run the equivalent checks you normally trust before a package-manager migration.

4. Commit

git add lpm.lock .npmrc package.json
test ! -f lpm.lockb || git add lpm.lockb
git rm yarn.lock yarn.lock.backup .npmrc.backup
git commit -m "Migrate to LPM CLI"

Do not commit .backup files unless you intentionally keep migration rollback artifacts in the repository.

Yarn-Specific Notes

yarn.lock resolved URLs from registry.yarnpkg.com are normalized into registry package entries when possible.
Berry lockfiles are detected through the __metadata block. npm: descriptors such as react@npm:^18 are resolved to the exact versions pinned in yarn.lock.
Berry's .pnp.cjs / Plug'n'Play runtime is not carried over. LPM CLI materializes node_modules/ using its hoisted or isolated linker.
Berry entries with local or non-registry protocols (workspace:, portal:, link:, file:, patch:, exec:, git:, git+, github:) are skipped and reported in the migration output.
dependencies and optionalDependencies blocks inside lockfile entries both contribute dependency edges.
The install step rebuilds node_modules. Single-package projects default to LPM CLI's hoisted v2 layout; workspaces and peer-conflict installs use isolated layout unless you override the linker.
Dependency lifecycle scripts remain denied by default. After migration, run lpm rebuild and lpm approve-scripts for packages that need install-time builds.

Rollback

lpm migrate --rollback

Restores backups from the previous migration run and removes LPM CLI files created by that run. Safe to run repeatedly.

Migrating from Yarn