Delegate Node-to-Bun Migration to an Agent with the bun-runtime Skill
機械翻訳 / Machine-translated

機械翻訳 / Machine-translated
Original article: Delegate Node-to-Bun Migration to an Agent with the bun-runtime Skill (cccskills)
Skill page: bun-runtime
Key takeaways from this article
With bun-runtime installed, you can have an AI agent handle everything — running code, managing dependencies, building, testing with bun test, and configuring Vercel — all assuming Bun.
This skill is aimed at developers working with JavaScript or TypeScript.
Below, we walk through how to replace Node, how to install the skill, example prompts, and what to verify before and after migration.
With bun-runtime installed, you can have an agent replace the execution, dependency management, and testing of a Node-based project with Bun equivalents.
Here's an example prompt:
Migrate this Node project to Bun.
I'd also like the tests to work with bun test.
The agent follows the skill's migration steps and replaces commands written for node and npm with their Bun counterparts.
Dependencies are reinstalled with bun install, and a text-format lockfile called bun.lock is created.
The command mapping looks like this:
| Node/npm syntax | Bun syntax |
|---|---|
| node script.js | bun run script.js or bun script.js |
| npm install | bun install |
| npm run dev | bun run dev |
| One-off execution with npx | bun x |
Tests are written by importing expect and test from bun:test.
Since the API is similar to Jest, you don't need to learn a completely new syntax from scratch.
bun-runtime is a set of instructions for using Bun in four roles: runtime (the environment that executes your program), package manager, bundler, and test runner.
Since everything from execution to production builds is handled by one tool, you can have the agent work in a consistent style throughout.
The skill also includes guidelines for choosing between Bun and Node.
Here's a reference table for when you're unsure:
| Choice | Best suited for |
|---|---|
| Bun | New JS/TS projects, scripts where install/run speed matters, Vercel deployments on the Bun runtime, when you want to consolidate execution/install/testing/building into one tool |
| Node | When ecosystem compatibility is the top priority, legacy tools that require Node, or packages with known issues under Bun |
TypeScript files can be executed directly, like bun src/index.ts.
Adding, removing, and updating dependencies is done with bun add, bun remove, and bun update, while bun outdated lists anything out of date.
Loading .env files at runtime is also within the skill's scope.
Monorepos — repositories that contain multiple packages — are also supported.
Listing workspaces in package.json works the same way as with npm or yarn.
To run a script scoped to a specific package, use bun run --filter.
File I/O, HTTP servers, SQLite, SQL databases, Redis, and S3-compatible storage can all be handled with Bun's built-in features.
The skill's philosophy is to reach for built-ins before adding external packages.
The built-in bundler and transpiler are used to package apps or libraries for distribution.
Builds are run with bun run build or in the form bun build ./src/index.ts --outdir=dist.
The command to run all tests is bun test.
Add --watch to re-run tests automatically as files change.
For CI, options available in Bun 1.4 are also documented:
| Option | Purpose |
|---|---|
| --changed | Run only tests affected by changes |
| --parallel | Run tests in parallel using worker processes |
| --shard=<n>/<count> | Split and run tests across CI jobs |
| --isolate | Run each file in a fresh global environment |
On Vercel, you specify Bun 1.4 by adding bunVersion to vercel.json.
Installation at deploy time is done with bun install --frozen-lockfile to reproduce dependencies exactly as defined in the lockfile.
{
"bunVersion": "1.4.x"
}
Installation takes just one command.
With npx skills add, you can choose which agent to install into — Claude Code, Codex, and others are supported.
npx skills add https://github.com/affaan-m/ECC --skill bun-runtime
If you'd prefer to have your agent install it for you, send the following message as-is:
Please install the following Agent Skill.
https://github.com/affaan-m/ECC/tree/main/skills/bun-runtime
First, review the contents of SKILL.md and any accompanying files to confirm there are no suspicious operations (such as sending data externally or reading credentials). Then place it at ~/.claude/skills/bun-runtime/ for Claude Code, or ~/.agents/skills/bun-runtime/ for Codex.
The installation location depends on whether you want to use the skill across all projects or only in a specific one.
| Agent | All projects | Specific project only |
|---|---|---|
| Claude Code | ~/.claude/skills/ | .claude/skills/ in the project |
| Codex | ~/.agents/skills/ | .agents/skills/ in the project |
The skill contains just one file: SKILL.md.
The source is affaan-m/ECC, licensed under MIT.
The three main use cases are: starting a new project, migrating an existing project, and setting up tests and deployment configuration.
I want to build a new API server in TypeScript.
Start with Bun and include test and build configuration too.
This prompt results in an HTTP server using Bun.serve and a test file written with bun:test.
Dependencies are installed via bun install, and the build outputs to dist using bun build.
Outline the steps to migrate this Node project to Bun and list what to check for compatibility.
The response includes a command substitution table and instructions for creating a lockfile with bun install.
It also flags dependencies that rely on native extensions or Node-specific internals as items requiring attention.
Write tests with bun test and set up a build configuration for Vercel.
You'll get a test file and a vercel.json with bunVersion specified.
The deployment steps use bun install --frozen-lockfile and bun run build.
Because this skill is a set of instructions for using Bun's commands, you need Bun itself installed on your machine.
The instructions are based on Bun 1.4.x.
CLI flags can change between versions, so run bun --version to confirm your version before proceeding.
Bun's Node compatibility is not complete.
Some native extensions, rarely-used node: internal APIs, and packages that rely on Node-specific internals may fail.
Always run your tests after migrating, and verify that everything works before relying on it in production.
Dependency operations also warrant care.
bun audit queries the registry for the package names and versions listed in bun.lock.
If you have private internal packages, check what gets sent and where.
bun audit fix updates dependencies and reinstalls them, which means your lockfile and installed packages will change.
--isolate separates the global environment per file — it is not a process or security sandbox.
Review the contents of vercel.json before applying it.
For the skill itself, it's a good idea to read through SKILL.md before installing.
No.
Most packages will work, but compatibility is not 100%.
Packages that rely on native extensions or Node-specific internals need to be verified before migration.
The current Bun standard is the text-format bun.lock.
The old binary-format bun.lockb can still be read for migration purposes.
New projects use bun.lock.
Yes.
Committing bun.lock to reproduce the same dependencies is listed as a best practice in the skill.
On Vercel, this is used together with --frozen-lockfile.
The instructions are written with Bun 1.4.x as the baseline.
When using a different version, check the help output or documentation for your installed version to confirm flag availability.
bun-runtime is a consolidated set of instructions covering Bun-based execution, dependency management, building, testing, and Vercel configuration.
For Node migrations, the agent takes care of mapping out command replacements and compatibility checkpoints.
That said, make sure you personally run the tests after migration and review vercel.json yourself.
For more details, see the cccskills page.
This article is a repost of "Delegate Node-to-Bun Migration to an Agent with the bun-runtime Skill" from cccskills.
Skill details and installation instructions can be found on the cccskills bun-runtime page.