/bun:add

Add a package to dependencies using Bun.

When to Use This Skill

| Scenario | Use this skill | Alternative | |----------|---------------|-------------| | Quickly adding a single package | Yes | N/A | | Adding a dev dependency | Yes | N/A | | Pinning an exact package version | Yes | N/A | | Installing all project dependencies | No - use bun-package-manager | bun install | | Removing or updating packages | No - use bun-package-manager | N/A | | Managing workspace dependencies | No - use bun-package-manager | N/A |

Parameters

Parse $ARGUMENTS. These are supplied by the caller; nothing substitutes them for you.

| Token in $ARGUMENTS | Binds | Default when absent | |---|---|---| | First non-flag token (required) | PACKAGE — name, optionally with a version (lodash, react@18) | none — ask for it rather than guessing | | --dev | add to devDependencies | added to dependencies | | --exact | pin the exact version (no ^ range) | caret range |

Execution

Pick the row matching the flags the caller passed, substitute PACKAGE, and run it:

| Flags in $ARGUMENTS | Command | |---|---| | (none) | bun add PACKAGE | | --dev | bun add --dev PACKAGE | | --exact | bun add --exact PACKAGE | | --dev --exact | bun add --dev --exact PACKAGE |

Examples

# Add runtime dependency
bun add express

# Add dev dependency
bun add --dev typescript vitest

# Pin exact version
bun add --exact react@18.2.0

# Add to specific workspace
bun add lodash --cwd packages/utils

# Preview without writing package.json
bun add --dry-run zod

An unpinned `bun add` bypasses the lockfile

bun install --frozen-lockfile governs only what that install resolves. A later bun add <pkg> with no version resolves the registry's latest dist-tag at run time, and the lockfile does not apply to it. The usual place this happens is a Dockerfile that installs with --production (to skip dev packages) and then re-adds one CLI from devDependencies.

latest is a registry convention, not a stability guarantee. Publishers can tag a prerelease as latest.

Observed 2026-08: bun add --dev prisma in a --production Docker stage pulled 8.0.0-rc.12, because npm's latest for prisma was a release candidate. Its CLI had no generate command, so the image build failed at a commit that touched neither Prisma nor the Dockerfile. Another image built from a plain --frozen-lockfile install kept working, which is the sign that a version was being resolved rather than locked. Unit-test CI stayed green because it never built the image.

When an install line has to name a package that the primary install skipped, read the version from package.json instead of hardcoding a second copy. That keeps one source of truth, and Renovate keeps bumping it:

RUN bun add --dev "prisma@$(bun -e 'console.log(JSON.parse(await Bun.file("package.json").text()).devDependencies.prisma)')"

If package.json holds a range (^7.9.1), this resolves the highest version inside that range, which may differ from the locked one. Pin exact versions in package.json when that difference matters.

Post-add

Report package version added
Show dependency tree impact with bun why <package>
Suggest running tests to verify compatibility