Agent-Skills.md

Agent Skills: Bun Dev

Definitive, rule-first Bun development/build/runtime guidance + automation. Use when adopting Bun, migrating a repo from Node.js, auditing/fixing Bun package management (bun.lockb, bun install), optimizing scripts/monorepos (bun run --parallel/--sequential, --workspaces/--filter), configuring Bun + TypeScript, using bun test/build, tuning performance, or deploying Bun workloads/Vercel Functions with the Bun runtime (bunVersion, limitations, Next.js ISR scripts).

UncategorizedID: bjornmelin/dev-skills/bun-dev

Repository

bjornmelin/dev-skills
BjornMelin
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/BjornMelin/dev-skills/tree/HEAD/skills/bun-dev

Skill Files

Browse the full folder contents for bun-dev.

Download Skill

Loading file tree…

skills/bun-dev/SKILL.md

Skill Metadata

Name
bun-dev
Description
"Definitive, rule-first Bun development/build/runtime guidance + automation. Use when adopting Bun, migrating a repo from Node.js, auditing/fixing Bun package management (bun.lockb, bun install), optimizing scripts/monorepos (bun run --parallel/--sequential, --workspaces/--filter), configuring Bun + TypeScript, using bun test/build, tuning performance, or deploying Bun workloads/Vercel Functions with the Bun runtime (bunVersion, limitations, Next.js ISR scripts)."

Bun Dev

Rule-first Bun guidance plus a shared audit/remediation engine.

Use bun-dev for operating-model decisions, rule lookup, release sync, and platform routing. Use bun-audit when the task is specifically about scanning a repo, planning safe fixes, applying deterministic remediations, or validating changes against Bun policy.

Start with rules/_index.md for discovery, then route by the Priority Table below.

Navigation (How To Use This Skill)

  1. If changing package manager/runtime, open P1 rules first: pm-*, runtime-*, vercel-*.
  2. If working in a monorepo, open: scripts-bun-run-parallel-sequential, scripts-bun-filter-and-workspaces.
  3. If deploying to Vercel, open: vercel-bun-runtime-enable, vercel-bun-runtime-limitations.
  4. For repo-wide enforcement, use the shared CLI: bun-platform audit, plan-fixes, apply-safe-fixes, validate.
  5. For “what changed recently?” (Bun v1.3.10), refresh references and open: references/ref-bun-release-notes-bun-v1.3.10.md.

Quick Start (Audit -> Fix -> Verify)

Audit (report-only):

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts audit --root . --format text

Plan safe fixes:

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts plan-fixes --root .

Apply safe fixes:

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts apply-safe-fixes --root .

Validate after remediation:

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts validate --root . --fail-on warn

Priority Table (Route To The Right Rules)

| Priority | Category | Impact | Prefix | | --- | --- | --- | --- | | 1 | Package manager + lockfiles | CRITICAL | pm- | | 1 | Runtime selection + “one runtime where possible” | CRITICAL | runtime- | | 1 | Vercel Bun runtime | CRITICAL | vercel- | | 2 | Scripts + monorepo orchestration | HIGH | scripts- | | 2 | TypeScript + tooling | HIGH | tsconfig- | | 3 | Testing | MEDIUM | test- | | 3 | Bundling + build | MEDIUM | build- | | 4 | Performance | MEDIUM | perf- | | 5 | Migration + troubleshooting | LOW/MED | migrate-, troubleshooting- |

Quick Reference (Start Here)

1) Package Manager + Lockfiles (CRITICAL)

  • pm-bun-add-remove-update
  • pm-no-mixed-lockfiles
  • pm-commit-bun-lockb
  • pm-bun-install-ci-frozen-lockfile
  • pm-package-manager-field
  • pm-bunx-vs-npx

2) Runtime Selection (CRITICAL)

  • runtime-bun-vs-node-choose
  • runtime-bun-run-bun-flag
  • runtime-ts-direct-execution
  • runtime-watch-and-hot-reload
  • runtime-env-files

3) Vercel Bun Runtime (CRITICAL)

  • vercel-bun-install-detection
  • vercel-bun-runtime-enable
  • vercel-bun-runtime-limitations
  • vercel-nextjs-bun-runtime-scripts
  • vercel-bun-function-fetch-handler

4) Scripts + Monorepos (HIGH)

  • scripts-bun-run-parallel-sequential
  • scripts-bun-filter-and-workspaces
  • scripts-no-npm-in-bun-repos

5) TypeScript (HIGH)

  • tsconfig-bun-recommended
  • tsconfig-bun-types
  • tsconfig-module-resolution-bundler

6) Testing + Build (MEDIUM)

  • test-bun-test-runner
  • test-bun-retry
  • test-mocking-and-spying
  • build-bun-build-bundler
  • build-compile-executables
  • build-bun-compile-browser

7) Performance (MEDIUM)

  • perf-prefer-bun-native-apis
  • perf-avoid-node-fs-promises-hot-paths

8) Migration + Troubleshooting (LOW/MED)

  • migrate-node-to-bun-checklist
  • troubleshooting-esm-cjs-and-exports
  • troubleshooting-types-bun

References (Vendor Docs Snapshots)

Start with references/index.md.

Shared Platform Commands

  • audit: report Bun findings in text, md, or json
  • list-rules: print all rule ids
  • explain <rule-id>: print the matching rule file
  • plan-fixes: print deterministic safe fix candidates
  • apply-safe-fixes: apply safe file rewrites only
  • validate: rerun the audit and fail on a severity threshold
  • benchmark: emit audit/fix-planning timings
  • release-sync: refresh Bun/Vercel references and rebuild rule indexes

Platform state:

  • .bun-platform/cache.sqlite: shared scan cache
  • .bun-platform/rollbacks/: safe-fix rollback artifacts
  • references/release-sync-report.json: local generated release intelligence summary (ignored; not committed)

Config file:

  • bun-platform.config.json
    • disabledRules
    • severityOverrides
    • adapters
    • includePaths
    • excludeDirs
    • baseline
    • maxFiles
    • maxBytes
    • validationCommands
    • manageGitignore
  • Example template: assets/templates/bun-platform.config.example.json

Reference Map

| Topic | Reference | Start with rules | | --- | --- | --- | | Bun v1.3.10 release notes | references/ref-bun-release-notes-bun-v1.3.10.md | scripts-bun-run-parallel-sequential, build-bun-compile-browser, test-bun-retry, test-bun-test-runner | | Vercel Bun runtime | references/ref-vercel-bun-runtime.md | vercel-bun-runtime-enable, vercel-bun-runtime-limitations |

Refresh reference snapshots:

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts release-sync

Automation

Shared CLI:

bun ~/.agents/skills/bun-dev/scripts/bun-platform.ts audit --root .

Compatibility wrapper:

bun ~/.agents/skills/bun-dev/scripts/bun-audit.ts audit --root .

Skill integrity check (rule ids, indexes, flat references):

bun ~/.agents/skills/bun-dev/scripts/check-skill-integrity.ts