Migrating from Bun guide

lpm migrate converts a Bun 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 Bun-specific parts. For the full flag reference, see lpm migrate.

Prerequisites

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

bun.lock is the direct path. When bun.lockb is selected, LPM CLI first looks for a sibling bun.lock; if it exists, LPM CLI parses that text lockfile instead. If no sibling text lockfile exists, LPM CLI runs bun bun.lockb and parses the emitted JSON. If the bun binary is unavailable, migration exits with a clear error.

1. Preview

lpm migrate --dry-run

Dry-run detects Bun, parses the selected lockfile, 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.

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 Bun package entries, exact versions, tarball URLs, integrity strings, dependency edges, and dev/optional metadata.
Write a version 12 staging lpm.lock. If the graph fits the binary format, write lpm.lockb.
Back up the Bun lockfile, .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 Bun project used scripts that shell out through bun, keep Bun installed wherever those scripts run; migration changes the package manager, not your project scripts.

4. Commit

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

Only remove files that exist in your repo. Do not commit .backup files unless you intentionally keep migration rollback artifacts in the repository.

Bun-Specific Notes

bun.lock JSON is parsed directly.
bun.lockb needs either a sibling bun.lock or the bun binary available during migration.
Bun lockfile metadata carries dev and optional package flags, so the converted lockfile preserves those package classifications.
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 Bun