Bun Package Manager: English for Modern JavaScript Tooling

Bun is a fast JavaScript runtime that ships with its own built-in package manager, test runner, and bundler. Its package manager is a drop-in replacement for npm and Yarn, but uses its own binary lockfile format for speed. If your team has switched to Bun, or if you are evaluating it, you will need to understand the specific vocabulary Bun uses so you can follow its documentation and discuss it confidently in English.

Installation Commands

bun install — the command that reads your package.json, resolves all dependencies, and writes them to node_modules; it is significantly faster than npm install because it uses a native binary resolver.

“The CI pipeline runs bun install at the start of every job to ensure all dependencies are available before the build step.”

bun add — the command for adding a new package to your project, equivalent to npm install package-name; it updates both package.json and the lockfile automatically.

“I ran bun add zod to add the validation library, and the lockfile was updated in under a second.”

bun remove — the command for uninstalling a package and removing it from package.json and the lockfile in one step.

“We ran bun remove lodash after migrating all utility functions to native JavaScript methods.”

Lockfile and Reproducibility

bun.lock — the text-based lockfile format introduced in Bun 1.1 that records the exact resolved version of every dependency; it replaces the older binary bun.lockb file and is human-readable and diff-friendly.

“The code review was much easier after we switched to bun.lock because we could see exactly which dependency versions changed in the pull request.”

lockb file — the original binary lockfile format used by older versions of Bun; it cannot be read as text and produces unintelligible diffs, which is why bun.lock was introduced as a replacement.

“Our repository had a lockb file from an older Bun version, so we deleted it and ran bun install to generate the new bun.lock format.”

—frozen-lockfile — a flag passed to bun install that prevents Bun from updating the lockfile during installation; if the lockfile is out of sync with package.json, the command fails instead of silently updating it.

“We always pass —frozen-lockfile in CI to guarantee that deployments use exactly the dependency versions that were reviewed and approved.”

Workspaces and Monorepos

workspace — a feature that allows multiple packages inside a single repository to share a single node_modules folder and a single lockfile, avoiding duplicate installations.

“We configured a workspace so the shared UI library and the main application can both be developed in the same repository without duplicating dependencies.”

workspace protocol — the workspace:* version specifier you can use in package.json to reference another package inside the same monorepo rather than fetching it from the npm registry.

“The web app’s package.json uses the workspace protocol for the design-system package so local changes are reflected immediately without publishing.”

Dependency Types and Resolution

peer dependency — a package that your library requires the consuming project to provide, rather than bundling it itself; declared in the peerDependencies field of package.json.

“Our component library lists React as a peer dependency because it should not ship its own copy of React alongside the host application’s copy.”

override — an entry in the overrides field of package.json that forces a specific version of a nested dependency across the entire dependency tree, useful for patching security vulnerabilities.

“We added an override to force all packages in the tree to use a patched version of the vulnerable serialisation library.”

optional dependency — a package listed under optionalDependencies that Bun will attempt to install but will not treat as an error if installation fails, commonly used for platform-specific native modules.

“The image processing library is listed as an optional dependency because it requires a native binary that may not compile on all CI environments.”

Practice

Run bun install --frozen-lockfile in a project and observe the output. Then try bun add a small utility package and inspect the changes in bun.lock using git diff. Write two sentences in English describing what changed and why the lockfile is important for team collaboration.