--- name: bun-package-manager-13d37df8e851 description: Bun package manager commands (install, add, remove, update), workspaces, lockfiles, npm/yarn/pnpm migration. Use for dependency management with Bun. license: MIT --- # Bun Package Manager Bun's package manager is a dramatically faster replacement for npm, yarn, and pnpm. Up to **25x faster** than npm install. ## Quick Start ```bash # Install all dependencies bun install # Add packages bun add react react-dom bun add -D typescript @types/react # Remove packages bun remove lodash # Update packages bun update # Run package binaries bunx create-next-app ``` ## Core Commands | Command | Description | |---------|-------------| | `bun install` | Install all dependencies | | `bun add ` | Add dependency | | `bun add -D ` | Add dev dependency | | `bun add -O ` | Add optional dependency | | `bun add --peer ` | Add peer dependency | | `bun remove ` | Remove dependency | | `bun update [pkg]` | Update dependencies | | `bunx ` | Run package binary | | `bun pm cache rm` | Clear cache | ## Installation Flags ```bash # Production mode (no devDependencies) bun install --production # Frozen lockfile (CI/CD) bun install --frozen-lockfile bun ci # shorthand # Dry run bun install --dry-run # Verbose/Silent bun install --verbose bun install --silent # Force reinstall bun install --force # Global packages bun install -g cowsay ``` ## Lockfile Bun uses `bun.lock` (text-based since v1.2): ```bash # Generate text lockfile bun install --save-text-lockfile # Upgrade from binary bun.lockb bun install --save-text-lockfile --frozen-lockfile --lockfile-only rm bun.lockb ``` ## Workspaces (Monorepos) ```json { "name": "my-monorepo", "workspaces": ["packages/*", "apps/*"] } ``` Run commands across workspaces: ```bash # Run in matching packages bun run --filter 'pkg-*' build # Run in all workspaces bun run --filter '*' test # Install for specific packages bun install --filter 'pkg-a' ``` ## Lifecycle Scripts Bun does **not** run lifecycle scripts from dependencies by default (security). Whitelist trusted packages: ```json { "trustedDependencies": ["my-trusted-package"] } ``` ```bash # Skip all lifecycle scripts bun install --ignore-scripts # Concurrent scripts bun install --concurrent-scripts 5 ``` ## Overrides & Resolutions Force specific versions for nested dependencies: ```json { "overrides": { "lodash": "4.17.21" } } ``` Yarn-style resolutions also supported: ```json { "resolutions": { "lodash": "4.17.21" } } ``` ## Non-npm Dependencies ```json { "dependencies": { "dayjs": "git+https://github.com/iamkun/dayjs.git", "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21", "zod": "github:colinhacks/zod", "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz", "bun-types": "npm:@types/bun" } } ``` ## Installation Strategies > **Bun 1.3+ default flip**: Starting in Bun 1.3, **`isolated` is the default for workspaces** (packages can no longer reach undeclared deps through the hoisted root `node_modules`). `hoisted` is now the **legacy opt-out** — only use it when a workspace package depends on a transitive dep that it doesn't declare. ### Hoisted (legacy opt-out; still the default for single non-workspace packages) Traditional flat node_modules: ```bash bun install --linker hoisted ``` ### Isolated (default for workspaces in Bun 1.3+) pnpm-like strict isolation: ```bash bun install --linker isolated ``` Isolated prevents "phantom dependencies" - packages can only access declared dependencies. To make this explicit or restore it after an opt-out, set it in `bunfig.toml`: ```toml [install] linker = "isolated" # default for workspaces in Bun 1.3+ # linker = "hoisted" # legacy opt-out ``` ## CI/CD ```yaml # GitHub Actions - uses: oven-sh/setup-bun@v2 - run: bun ci # frozen lockfile ``` ## Platform-Specific ```bash # Install for different platform bun install --cpu=x64 --os=linux ``` ## Secure Installation When installing packages, follow supply chain security best practices: - **Block post-install scripts** — Bun disables them by default; allow specific packages via `trustedDependencies` in `package.json` - **Cooldown period** — Configure `minimumReleaseAge` in `bunfig.toml` to wait 7 days for new versions - **Audit before installing** — Run `socket package score npm ` or use `socket npm install ` to check packages before they reach your project Load the `dependency-upgrade` skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement. ## Common Errors | Error | Cause | Fix | |-------|-------|-----| | `Cannot find module` | Missing dependency | Run `bun install` | | `Lockfile mismatch` | package.json changed | Run `bun install` | | `Peer dependency` | Missing peer | `bun add` the peer | | `Lifecycle script failed` | Untrusted package | Add to `trustedDependencies` | ## Migration from Other Package Managers ### From pnpm Bun automatically migrates `pnpm-lock.yaml`: ```bash bun install # Auto-converts to bun.lock ``` Workspace config moves to package.json: ```json { "workspaces": { "packages": ["apps/*", "packages/*"], "catalog": { "react": "^18.0.0" } } } ``` ### From npm/Yarn Simply run `bun install` - Bun reads `package-lock.json` and `yarn.lock`. ## When to Load References Load `references/cli-commands.md` when: - Need complete CLI flag reference - Working with advanced options Load `references/workspaces.md` when: - Setting up monorepos - Configuring workspace filters Load `references/migration.md` when: - Migrating from npm/yarn/pnpm - Converting lockfiles --- Source attribution: secondsky Original project: https://github.com/secondsky/claude-skills/blob/88378361314f558fb719aec0af9fd898ab36f0b2/plugins/bun/skills/bun-package-manager/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 Claude Skills Maintainers Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: secondsky Original project: https://github.com/secondsky/claude-skills/blob/88378361314f558fb719aec0af9fd898ab36f0b2/plugins/bun/skills/bun-package-manager/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering Roles: Backend Developer, Frontend Developer, Full-Stack Developer Specialties: DevOps, Frontend, Git, React, Testing Tools: Bun Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: bba717b97b4a61ae802d1c45e84b6cd462c83a1cdf5eb4a51ebac3b2b17fc47a