bun add: Add Dependencies to package.json

bun add installs one or more packages and writes them into the correct dependency section of package.json.

bun add is how you grow the dependency tree. It is rarely run in CI itself, but the flags it writes (exact versions, dev vs prod) shape what install does on every later run.

What it does

bun add fetches the named package(s), installs them, and records them in package.json under dependencies (or devDependencies with --dev). It updates bun.lock and links the package into node_modules. Without --exact it writes a caret range.

Common usage

Terminal

bun add react
bun add --dev typescript            # devDependency
bun add --exact zod                 # pin exact version, no caret
bun add react@18.3.1                # specific version
bun add --global @biomejs/biome     # global tool

Options

Flag	What it does
--dev / -d	Add to devDependencies
--optional	Add to optionalDependencies
--peer	Add to peerDependencies
--exact / -E	Pin the exact version (no caret range)
--global / -g	Install as a global tool
--ignore-scripts	Skip lifecycle scripts during the add

In CI

Avoid bun add inside pipelines; it mutates package.json and bun.lock, which breaks --frozen-lockfile reproducibility on the next job. Use --exact in development for tools whose minor bumps break builds, then commit the lockfile so CI installs the same tree.

Common errors in CI

"error: <package>@<version> failed to resolve" means the version does not exist on the registry or a private scope lacks auth. "error: Lockfile is frozen" appears if you run bun add under CI=true with a frozen flag set; do the add locally. "InvalidPackageName" means a malformed name, often a stray @ or space.