install: lockfile & migration

22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

bun install creates bun.lock lockfile by default

bun install automatically converts package-lock.json to Bun's bun.lock lockfile format, preserving existing resolved dependency versions. This lockfile is used as the source of truth for installed packages.

Configure global git config for .lockb diff

To configure git diff for .lockb files globally across all repositories, run these git config commands: git config --global diff.lockb.textconv bun and git config --global diff.lockb.binary true

How textconv and binary flags work for lockfile diffing

The textconv configuration tells git to run bun on the file before diffing. The binary configuration tells git to treat the file as binary so it doesn't try to diff it line-by-line. Running bun on the lockfile (bun ./bun.lockb) prints a human-readable version of it, which git diff then uses for comparison.

Configure .gitattributes for .lockb binary diff

To teach git how to generate a human-readable diff of Bun's binary lockfile format (.lockb), add the following line to your local or global .gitattributes file: *.lockb binary diff=lockb

bun.lock JSONC format introduced in v1.1.39

Bun v1.1.39 introduced bun.lock, a JSONC formatted lockfile that is human-readable and git-diffable without configuration and at no cost to performance. In version 1.2.0 and later, bun.lock is the default format for new projects.

Lockfile tracks catalog definitions and resolutions

Bun's lockfile includes the catalog definitions from package.json and the resolution of each cataloged dependency. The lockfile contains a catalog field and catalogs object that mirror the root package.json structure, ensuring consistent installs across environments.

Example lockfile structure with catalogs

Bun's lockfile (bun.lock) includes catalog definitions and workspace dependencies: ```json { "lockfileVersion": 2, "workspaces": { "": { "name": "react-monorepo" }, "packages/app": { "name": "app", "dependencies": { "react": "catalog:" } } }, "catalog": { "react": "^19.0.0" }, "catalogs": { "testing": { "jest": "29.6.2" } }, "packages": {} } ```

pnpm catalog: protocol preservation

Bun preserves dependencies that use pnpm's 'catalog:' protocol. Dependencies like 'react': 'catalog:' or 'webpack': 'catalog:build' are maintained in the migrated bun.lock.

bun install download timing for packages

When bun.lock doesn't exist or package.json has changed dependencies, Bun downloads and extracts tarballs eagerly while resolving. When bun.lock exists and package.json hasn't changed, Bun downloads missing dependencies lazily. If the package with matching name and version already exists in the expected location within node_modules, Bun doesn't attempt to download the tarball.

bun.lock text lockfile format

bun.lock is Bun's lockfile format using a text-based format. Before Bun 1.2, the lockfile was binary and called bun.lockb. To upgrade an old lockfile to the new format, run 'bun install --save-text-lockfile --frozen-lockfile --lockfile-only', then delete bun.lockb.

pnpm migration automatic detection and process

When Bun detects a pnpm-lock.yaml file and no bun.lock file exists, it automatically converts the lockfile to bun.lock during installation. The original pnpm-lock.yaml file remains unmodified. Migration only runs when bun.lock is absent. There is currently no opt-out flag for pnpm migration.

pnpm lockfile migration details

Bun converts pnpm-lock.yaml (lockfile versions 7–9, including pnpm 11's multi-document files) to bun.lock. It preserves resolved versions and integrity hashes. It preserves peer dependency ranges and peerDependenciesMeta. It migrates git, GitHub, tarball URL, file:, and npm: alias dependencies, including transitive ones. It resolves pnpm named registries via namedRegistries in pnpm-workspace.yaml. It converts injected workspace packages to ordinary workspace dependencies. It handles patched dependencies. It skips runtime: entries with a warning.

pnpm configuration migration to package.json

Bun migrates pnpm configuration: Overrides from pnpm.overrides move to root-level overrides in package.json. Patched Dependencies from pnpm.patchedDependencies move to root-level patchedDependencies in package.json. Workspace Overrides are applied from pnpm-workspace.yaml to root package.json.

pnpm migration requirements and limitations

Migration requires pnpm lockfile version 7 or higher. Workspace packages must have a name field in their package.json. All catalog entries referenced by dependencies must exist in the catalogs definition. Every workspace in pnpm-lock.yaml must have its package.json on disk. Relative link: dependencies and git dependencies with a sub-directory are not supported. If migration fails, Bun prints why and resolves from scratch instead. After migration, you can safely remove pnpm-lock.yaml and pnpm-workspace.yaml files.

Migration from npm/Yarn to isolated installs

To migrate from npm or Yarn to isolated installs: remove existing node_modules and lockfiles with 'rm -rf node_modules package-lock.json yarn.lock', then install with 'bun install --linker isolated'.

Migration from pnpm to isolated installs

To migrate from pnpm to isolated installs: remove pnpm files with 'rm -rf node_modules pnpm-lock.yaml', then install with 'bun install --linker isolated'. The layouts are similar—Bun hardlinks (clones on macOS) packages from its global cache into a per-project store at node_modules/.bun/ and symlinks top-level node_modules entries into it.

bun install creates bun.lock lockfile by default

The bun install command creates a lockfile called bun.lock. This lockfile should be committed to git.

--lockfile-only flag generates lockfile without installing

The --lockfile-only flag generates a lockfile without installing to node_modules. Bun always saves the lockfile to disk even if it is already up to date with package.json, except when --frozen-lockfile or --production is set. The bun add, bun remove, and bun update commands also accept the --lockfile-only flag.

--no-save flag installs without creating lockfile

Use the --no-save flag with bun install to install without creating a lockfile.

--yarn flag writes Yarn lockfile alongside bun.lock

Use the --yarn flag with bun install to write a Yarn lockfile in addition to bun.lock. This can also be configured in bunfig.toml under [install.lockfile] with print = "yarn", which is the only supported non-Bun lockfile format.

Text-based bun.lock migration from binary bun.lockb

Bun v1.2 changed the default lockfile format to text-based bun.lock. To migrate an existing binary bun.lockb, run bun install --save-text-lockfile --frozen-lockfile --lockfile-only and delete bun.lockb.

Automatic lockfile migration from other package managers

When running bun install in a project without bun.lock, Bun automatically migrates existing lockfiles from yarn.lock (v1), package-lock.json (npm lockfileVersion 2, 3, or 4), and pnpm-lock.yaml. Bun does not migrate package-lock.json from npm 6 or older (lockfileVersion 1); it prints a warning and resolves from package.json instead. Bun preserves the original lockfile, which can be removed manually after verification.

Give your agent this brain