diff --git a/.agents/skills/bun-runtime/SKILL.md b/.agents/skills/bun-runtime/SKILL.md index 452452278..5bd36c241 100644 --- a/.agents/skills/bun-runtime/SKILL.md +++ b/.agents/skills/bun-runtime/SKILL.md @@ -17,19 +17,19 @@ Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/te ## How It Works -- **Version baseline**: guidance below targets Bun 1.4.x. Check the actual version with `bun --version` before relying on flag names, since CLI flags have changed across major versions. +- **Version baseline**: guidance below targets Bun 1.4.x. Check the actual version with `bun --version` before relying on flag names, since CLI flags can change between releases. - **Runtime**: Drop-in Node-compatible runtime, built on JavaScriptCore. As of Bun 1.4 the runtime itself is implemented in Rust (migrated from Zig). Not 100% Node-compatible — some native addons, less-common `node:` internal APIs, and packages that depend on Node-specific internals can still fail; verify before depending on it in production. -- **Package manager**: `bun install` is typically faster than npm/yarn; actual gains depend on project size, network conditions, and cache state. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary) — Bun still reads that format for migration, but new projects should use `bun.lock`. +- **Package manager**: Bun includes a package manager; installation performance depends on the project, network conditions, and cache state. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary) — Bun still reads that format for migration, but new projects should use `bun.lock`. - **Bundler**: Built-in bundler and transpiler for apps and libraries. - **Test runner**: Built-in `bun test` with a Jest-like API. **Migration from Node**: Replace `node script.js` with `bun run script.js` or `bun script.js`. Run `bun install` in place of `npm install`; most packages work. Use `bun run` for npm scripts; `bun x` for npx-style one-off runs. Node built-ins are supported; prefer Bun APIs where they exist for better performance. -**Package and workspace commands**: `bun add ` / `bun remove ` / `bun update [pkg]` manage dependencies; `bun outdated` lists stale deps; `bun pm ls` shows the dependency tree derived from the lockfile (not a listing of what's actually on disk). Read-only inspection: `bun audit` reads `bun.lock` and sends the package list to the npm advisory endpoint (or each scoped registry's own advisory endpoint) to report known vulnerabilities — it doesn't touch local files, but it isn't offline, so on private projects only use an approved registry/advisory endpoint, since package names and versions (including private ones) leave the machine. Modifying: `bun audit fix` applies fixes, `bun dedupe` collapses duplicate installs, and `bun prune` removes packages no longer referenced. Monorepos use a root `workspaces` array in `package.json` (same convention as npm/yarn); run a script in one workspace with `bun run --filter