Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 39 ยท Package Manager and Scripts

package.json, the Lockfile and the Cache

Understand package.json fields, the text bun.lock lockfile, migration from npm, yarn and pnpm, lifecycle script safety with trustedDependencies, bun pm commands, why and audit, and the global cache.

After you install a few packages, three things quietly control how your project behaves: package.json (what you asked for), the lockfile (what you got) and the cache (where the downloads live). Understanding all three removes most mystery from dependency problems like "works on my machine" and "why is this package here?". This lesson covers the important package.json fields, the bun.lock file format, safe handling of install scripts, inspection commands and cache management.

Important package.json fields

JSON
{
  "name": "tutorial-api",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "main": "src/index.ts",
  "bin": { "tutorial": "./src/cli.ts" },
  "exports": {
    ".": "./src/index.ts",
    "./utils": "./src/utils.ts"
  },
  "files": ["src", "README.md"],
  "engines": { "bun": ">=1.2.0" },
  "scripts": { "dev": "bun --watch src/index.ts" },
  "dependencies": {},
  "devDependencies": {},
  "trustedDependencies": [],
  "overrides": {},
  "workspaces": []
}
Field Meaning
name, version Identity. Needed only if you publish.
private true prevents accidental publishing; required for a workspace root.
type "module" makes .js files ES modules for tools that follow Node rules.
main, module, exports Entry points when someone imports your package. exports is the modern, precise form.
bin Command names that get linked into node_modules/.bin.
files What bun publish and bun pm pack include.
engines Documents (does not enforce) which runtimes are supported.
scripts Named commands; see Scripts and bunx.
trustedDependencies Dependencies allowed to run install scripts (below).
overrides, workspaces Covered in later lessons.

Bun reads this file as plain JSON, so comments and trailing commas are not allowed in package.json even though the lockfile (below) tolerates them.

The lockfile: bun.lock

bun install writes bun.lock, a text file in a JSON-with-commas format (JSONC). It records, for every package in your tree, the exact version resolved, its integrity hash, and its own dependencies. A shortened example looks like this:

JSONC
{
  "lockfileVersion": 1,
  "workspaces": {
    "": {
      "name": "tutorial-api",
      "dependencies": {
        "zod": "^3.25.0",
      },
    },
  },
  "packages": {
    "zod": ["[email protected]", "", {}, "sha512-AbC..."],
  },
}

Because it is plain text, Git diffs are readable and merge conflicts can be fixed by hand or simply regenerated by running bun install again. Always commit this file.

Older Bun versions wrote a binary bun.lockb. Bun 1.2 made the text format the default. To convert, run:

Terminal
bun install --save-text-lockfile --frozen-lockfile --lockfile-only

then delete bun.lockb once you are happy. If you still have an old binary lockfile, Bun can print it with bun bun.lockb for review.

What the lockfile gives you

  • Reproducibility. Every developer and CI job installs the same versions; the semver range in package.json only matters when you deliberately update.
  • Speed. Bun skips most registry queries when the lockfile already answers them.
  • Integrity. Each tarball is checked against its hash, so a package changed on the registry cannot slip in unnoticed.

Migrating from npm, Yarn or pnpm

If the folder has package-lock.json, yarn.lock or pnpm-lock.yaml and no bun.lock, bun install reads the old file, keeps the same resolved versions, and writes bun.lock. Afterwards delete the old lockfile so the team uses one. This makes switching low-risk:

Terminal
bun install
rm package-lock.json
git add bun.lock

Install scripts and trustedDependencies

Some packages have lifecycle scripts (postinstall, install, prepare) that run code on your machine when installed. That is how native modules compile, but also a way for a malicious package to run commands. npm runs these by default. Bun does not run dependency scripts by default. Your own project's scripts run; the scripts of packages in node_modules do not, except for a built-in list of popular packages that are known to need them.

If a dependency needs its script, allow it explicitly:

Terminal
bun add --trust esbuild          # add and trust in one step
bun pm trust esbuild             # trust an installed package
bun pm untrusted                 # list packages whose scripts were skipped
bun pm default-trusted           # show the built-in allow list

Trusting writes it into package.json:

JSON
{ "trustedDependencies": ["esbuild"] }

Review each trust decision. You can also disable all scripts for a run with --ignore-scripts.

Inspecting what is installed

Terminal
bun pm ls                  # direct dependencies
bun pm ls --all            # the whole tree
bun why lodash             # why is lodash in the tree? (dependency chain)
bun info react             # registry metadata for a package
bun pm bin                 # where local executables live
bun audit                  # check installed versions against the vulnerability database

bun why is the quickest way to answer "who pulled this in?" before you decide whether to remove or override it.

A runnable stand-in can model the same idea: given a dependency tree, walk it and print every chain that reaches a package.

Node.js Stand-in: why is this package installed? (runs on Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

http-utils is required through two different parents, so removing one parent does not remove it. That is also why the lockfile stores one resolved version for the whole tree where possible.

The global cache

Every tarball Bun downloads goes into one cache and each project's node_modules links to it.

Terminal
bun pm cache            # print the cache directory (usually ~/.bun/install/cache)
bun pm cache rm         # delete the whole cache

Set BUN_INSTALL_CACHE_DIR to put the cache elsewhere (for example on the same disk as your projects, so hardlinks work, or in a persistent volume in CI). Caching packages across CI runs is one of the biggest speed gains available:

YAML
- uses: actions/cache@v4
  with:
    path: ~/.bun/install/cache
    key: bun-${{ hashFiles('bun.lock') }}

If an install behaves oddly (a half-downloaded package, a corrupt file), clearing the cache and running bun install --force fixes most cases.

Reading a lockfile in code

Because bun.lock is JSONC, you can inspect it with Bun itself. Real Bun can import it, but any JSONC-aware tool works. This stand-in strips the trailing commas of a small sample and counts packages:

Node.js Stand-in: count packages in a lockfile-like JSONC string (Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Good habits

  • Commit bun.lock; never edit it by hand except to resolve a merge, then run bun install.
  • Review lockfile changes in pull requests: a sudden new dependency deserves a look.
  • Use --frozen-lockfile (or bun ci) in CI and Docker builds.
  • Run bun audit and bun outdated regularly.
  • Treat trustedDependencies like a permission list: add entries deliberately.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the format of the default lockfile in Bun 1.2 and later?

    Bun 1.2 switched the default to the text bun.lock, which is readable and diff-friendly.
  2. 2. Do the install scripts of dependencies run by default in Bun?

    Bun skips dependency lifecycle scripts unless the package is trusted, which reduces supply-chain risk.
  3. 3. Which command tells you why a package is in your dependency tree?

    bun why prints the chain of dependencies that leads to the package.
  4. 4. What does bun pm cache rm do?

    It clears the shared download cache; the next install re-downloads what it needs.

Summary

  • package.json states what you want; bun.lock records exactly what was resolved; the cache holds downloaded tarballs.
  • bun.lock is a text file: commit it, review changes and use --frozen-lockfile in CI.
  • Bun migrates package-lock.json, yarn.lock and pnpm-lock.yaml automatically on the first install.
  • Dependency lifecycle scripts do not run unless a package is in trustedDependencies or Bun's default list.
  • bun pm ls, bun why, bun info and bun audit inspect your tree; bun pm cache manages the cache.

Next: Scripts and bunx