Migrating from npm guide

Convert an npm project, review dependency changes, and retain a usable rollback path.

Use lpm migrate from the directory with package.json and package-lock.json. npm lockfile versions 1, 2, and 3 are supported.

LPM CLI works with npm, private registries, and LPM.dev Registry. Install it with the installation guide.

For a monorepo, run migration from the workspace root. Member-directory migration fails before it changes files.

--rollback can still restore an older migration from the member directory that contains its recovery files.

Preview and convert

Commit the current project before migration. Keep the previous package manager available for rollback.

lpm migrate --dry-run
lpm migrate

Read the detected source, skipped entries, warnings, and workspace count before conversion.

If several supported lockfiles exist, the newest modification time selects the input. There is no source-selection flag.

Equal timestamps prefer bun.lockb, bun.lock, pnpm-lock.yaml, yarn.lock, then package-lock.json. Other lockfiles stay in place.

Migration writes a staging lockfile, configures .npmrc, installs dependencies online, and runs available root build and test scripts.

The online install resolves the manifest requirements again. Migration does not guarantee the exact versions from the previous lockfile.

At a workspace root, installation includes the workspace members. Verification runs the root scripts. Use your usual workspace checks too.

Workspace hooks that request the same install lock fail with a parent-installation conflict. Run those commands after migration.

The command is non-interactive. An existing lpm.lock requires --force. --yes does not imply that flag.

Review npm compatibility

LPM CLI uses public npm and private registries through .npmrc. An LPM.dev Registry account is unnecessary for public npm dependencies.

Migration preserves existing registry routing. Unless --no-npmrc is set, it adds a missing @lpm.dev:registry mapping.

Simple string-valued npm overrides are supported. Nested npm override objects are not equivalent to those simple overrides.

Override precedence is lpm.overrides, then overrides, then resolutions. See npm compatibility before translating complex rules.

Single-package installs default to a hoisted layout. Workspaces and default installs with peer conflicts select isolated layout.

The hoisted layout differs from npm's flat tree. Declare every imported package instead of relying on undeclared transitive dependencies.

For a shared linker choice:

package.json (additional field)

{
  "lpm": { "linker": "isolated" }
}

Use lpm install with --linker=hoisted or --linker=isolated for a one-run override.

Separate conversion from installation

For a conversion without dependency installation, verification scripts, or registry configuration:

lpm migrate --no-install --skip-verify --no-npmrc --no-ci --json

--no-install alone does not skip verification. Migration has no dedicated lpm.json fields.

The staging lockfile cannot support an offline or frozen install. Complete a mutable online install first:

lpm install --no-frozen-lockfile

The explicit flag also works where CI=true normally selects frozen installation.

Check the result

Run the project's existing checks, then replay the new lockfile:

lpm run build
lpm run test
lpm install --frozen-lockfile

Replace these script names with the checks that your project defines. lpm run preserves custom test commands and their arguments.

After the store contains every required package, you can check offline replay:

lpm install --frozen-lockfile --offline

--offline controls package-network work. Root lifecycle scripts can still contact the network.

Dependency scripts stay denied by default. Review blocked scripts before authorizing packages that require installation builds.

Commit the migration

Inspect the complete diff and the resolved dependency versions:

git status --short
git diff

Commit lpm.lock and the intended manifest, configuration, patch, and CI changes.

Review .npmrc before committing it. Store credentials in environment variables or a user-level file, not in the repository.

Keep .backup files and .lpm-migrate-manifest.json together until you accept the migration. Keep these recovery files out of commits.

Remove the old manager's tracked lockfile only after the team accepts the migration. Do not delete recovery snapshots to clean the Git diff.

For CI, replace the install step with lpm ci. Review generated templates before enabling them.

Roll back or retry

lpm migrate --rollback

Rollback restores or removes files recorded in .lpm-migrate-manifest.json. Other install changes, node_modules, store contents, and script output remain.

After rollback, run the previous manager's install command to restore its dependency layout.

For an install or verification failure, fix the reported cause before retrying:

lpm migrate --force

Repeated migration retains the first recovery snapshots. Keep them until you no longer need rollback.

Migrating from npm