# Change Package Manager

> Switch the project's package manager between npm, bun, and pnpm. Updates all config, scripts, documentation, CI workflows, and AI instructions. Use when initializing from template or switching package managers.

- Skill: `sahildave/change-package-manager` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sahildave/change-package-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sahildave/change-package-manager/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: sahildave (https://skillmd.com/u/sahildave)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sahildave/change-package-manager

---


Switch this project's package manager to **$ARGUMENTS**.

If `$ARGUMENTS` is not exactly `bun`, `pnpm`, or `npm`, ask the user which package manager they want.

## Command Mapping Reference

Detect the current package manager from `AGENTS.md` or `package.json` scripts. Use this table for all replacements:

| Context           | npm                  | bun                             | pnpm                             |
| ----------------- | -------------------- | ------------------------------- | -------------------------------- |
| Install deps      | `npm install`        | `bun install`                   | `pnpm install`                   |
| Run script        | `npm run X`          | `bun run X`                     | `pnpm run X`                     |
| CI frozen install | `npm ci`             | `bun install --frozen-lockfile` | `pnpm install --frozen-lockfile` |
| Add dep           | `npm install pkg`    | `bun add pkg`                   | `pnpm add pkg`                   |
| Add dev dep       | `npm install -D pkg` | `bun add -D pkg`                | `pnpm add -D pkg`                |
| Remove dep        | `npm uninstall pkg`  | `bun remove pkg`                | `pnpm remove pkg`                |
| Audit             | `npm audit`          | `bun audit`                     | `pnpm audit`                     |
| Global install    | `npm install -g pkg` | `bun install -g pkg`            | `pnpm add -g pkg`                |
| Execute binary    | `npx`                | `bunx`                          | `pnpm dlx`                       |
| Lock file         | `package-lock.json`  | `bun.lock`                      | `pnpm-lock.yaml`                 |

## Step 1: Functional Config

### package.json scripts

Read `package.json`. Replace the current PM's `run` command with the target PM's in all script values. For example, `npm run typecheck` becomes `bun run typecheck`.

### tauri.conf.json

Read `src-tauri/tauri.conf.json`. Update `beforeDevCommand` and `beforeBuildCommand`.

### GitHub Actions CI

Read `.github/workflows/release.yml` and apply the appropriate pattern:

**Target: bun**

- Replace the `Setup Node.js` step with:
  ```yaml
  - name: Setup Bun
    uses: oven-sh/setup-bun@v2
  ```
- Replace `npm ci` with `bun install --frozen-lockfile`

**Target: pnpm**

- Add a step before `Setup Node.js`:
  ```yaml
  - name: Setup pnpm
    uses: pnpm/action-setup@v4
  ```
- Change `cache: 'npm'` to `cache: 'pnpm'` in the setup-node step
- Replace `npm ci` with `pnpm install --frozen-lockfile`

**Target: npm**

- Ensure standard `actions/setup-node@v4` with `cache: 'npm'`
- Ensure `npm ci` for install step
- Remove any pnpm/bun setup steps

## Step 2: Lock File

- Delete the old lock file (whichever of `package-lock.json`, `bun.lock`, `pnpm-lock.yaml` exists)
- Run the target PM's install command to generate the new lock file

## Step 3: AI Instructions & Codex Config

Update these files, replacing PM commands contextually:

- **`AGENTS.md`**: Update rule 0 (the "Use npm only" line) to reflect the new PM. For example: `0. **Use bun only**: This project uses \`bun\`, NOT \`npm\`. Always use \`bun install\`, \`bun run\`, etc.`
- **`.Codex/skills/init/SKILL.md`**: Replace PM commands in verification/next-steps sections
- **`.Codex/skills/check/SKILL.md`**: Replace PM commands
- **`.Codex/agents/cleanup-analyzer.md`**: Replace PM commands
- **`.Codex/settings.local.json`**: Update `Bash(npm ...)` permission patterns to use the new PM (e.g. `Bash(bun run format:*)`)

## Step 4: Documentation

Use Grep to find all remaining references to the old PM across the codebase. Update every documentation file, making sentences read naturally — don't do blind find-replace on prose.

Key files to check:

- `README.md`
- `docs/USING_THIS_TEMPLATE.md`
- `docs/CONTRIBUTING.md`
- `docs/SECURITY.md`
- All files under `docs/developer/`
- `scripts/prepare-release.js` (help text)

## Step 5: Verify

Run a final search for any remaining references to the old PM:

```bash
grep -rn "OLD_PM_NAME" --include="*.md" --include="*.json" --include="*.yml" --include="*.js" --include="*.ts" . | grep -v node_modules | grep -v ".lock"
```

Review any remaining hits — some are intentional (`.gitignore` entries, `.cursorignore` patterns listing all PM artifacts).

## Important Rules

- **Do NOT change** `.gitignore` or `.cursorignore` — these intentionally list artifacts for all PMs
- **Do NOT change** references to `node_modules/` — all three PMs use this directory
- **Preserve natural prose** in docs — make sentences read correctly, don't just swap words
- **npx** → `bunx` (bun) or `pnpm dlx` (pnpm)
- If the target PM is already in use, inform the user and stop