
元記事: NodeからBunへの移行をbun-runtimeスキルでエージェントに任せる(cccskills)
スキルのページ: bun-runtime
この記事の結論
bun-runtimeを入れると、実行・依存パッケージ管理・ビルド・bun testでのテスト・Vercelの設定まで、Bun前提でAIエージェントに進めてもらえます。
JavaScriptやTypeScriptで開発している人向けのスキルです。
Nodeからの置き換え方、インストール方法、依頼文の例、移行の前後で確かめる点を順に紹介します。
bun-runtimeを入れると、Nodeで動いているプロジェクトの実行・依存管理・テストを、Bun前提でエージェントに置き換えさせられます。
依頼の例は次のとおりです。
このNodeプロジェクトをBunへ移行して。
テストもbun testで動くようにしてほしい
エージェントはスキルの移行手順に沿って、nodeやnpmで書かれたコマンドをBunのコマンドに置き換えます。
依存パッケージはbun installで入れ直され、テキスト形式のロックファイルbun.lockが作られます。
置き換えの対応は次の表のとおりです。
| Node・npmでの書き方 | Bunでの書き方 |
|---|---|
| node script.js | bun run script.jsまたはbun script.js |
| npm install | bun install |
| npm run dev | bun run dev |
| npxでの単発実行 | bun x |
テストはbun:testからexpectとtestを読み込む形で書かれます。
APIはJestに似ているため、書き方を一から覚え直す必要はありません。
bun-runtimeは、Bunをランタイム(プログラムを動かす実行環境)、パッケージマネージャー、バンドラー、テストランナーの4役で使うための手順書です。
実行から配布用ビルドまでを1つの道具にそろえられるので、エージェントに同じ流儀で作業させられます。
スキルには、BunとNodeのどちらを選ぶかの目安も入っています。
迷ったときの判断材料は次の表のとおりです。
| 選ぶもの | 向いている場面 |
|---|---|
| Bun | 新しいJS・TSプロジェクト、インストールや実行の速さが大事なスクリプト、BunランタイムでのVercelデプロイ、実行・インストール・テスト・ビルドを1つにまとめたいとき |
| Node | エコシステムとの互換性を最優先したいとき、Node前提の古いツール、Bunで既知の問題がある依存パッケージを使うとき |
TypeScriptのファイルは、bun src/index.tsのようにそのまま実行できます。
依存の追加・削除・更新はbun add、bun remove、bun updateで行い、古いものはbun outdatedで一覧にします。
.envファイルを読み込んで実行する書き方も、スキルの範囲です。
複数のパッケージを1つのリポジトリにまとめたモノレポにも対応しています。
package.jsonにworkspacesを並べる形は、npmやyarnと同じです。
特定のパッケージだけでスクリプトを動かすときはbun run --filterを使います。
ファイル読み書き・HTTPサーバー・SQLite・SQLデータベース・Redis・S3互換ストレージは、Bunの組み込み機能で書けます。
外部パッケージを足す前に、まず組み込み機能で済ませるのがスキルの方針です。
組み込みのバンドラーとトランスパイラーを使って、アプリやライブラリを配布用にまとめます。
ビルドはbun run buildか、bun build ./src/index.ts --outdir=distの形で実行します。
全テストを実行するコマンドはbun testです。
--watchを付ければ、ファイルの変更に合わせて再実行されます。
CI向けには、Bun 1.4で使えるオプションも整理されています。
| オプション | 用途 |
|---|---|
| --changed | 変更の影響を受けるテストだけを実行する |
| --parallel | ワーカープロセスで並列に実行する |
| --shard=<n>/<count> | CIでテストを分割して実行する |
| --isolate | ファイルごとに新しいグローバル環境で実行する |
Vercelでは、vercel.jsonにbunVersionを書いてBun 1.4を指定します。
デプロイ時のインストールはbun install --frozen-lockfileで行い、ロックファイルどおりの依存を再現します。
{
"bunVersion": "1.4.x"
}
インストールに必要なのはコマンド1行だけです。
npx skills addでは、Claude CodeやCodexなどから入れる先のエージェントを選べます。
npx skills add https://github.com/affaan-m/ECC --skill bun-runtime
エージェントに入れてもらう場合は、次の文面をそのまま送ってください。
次の Agent Skill をインストールしてください。
https://github.com/affaan-m/ECC/tree/main/skills/bun-runtime
まず SKILL.md と付属ファイルの中身を確認し、不審な処理(外部への送信、認証情報の読み取りなど)がないことを確かめてから、Claude Code なら ~/.claude/skills/bun-runtime/、Codex なら ~/.agents/skills/bun-runtime/ に配置してください。
置き場所は、全プロジェクトで使うか、特定のプロジェクトだけで使うかで変わります。
| エージェント | 全プロジェクトで使う | 特定のプロジェクトだけで使う |
|---|---|---|
| Claude Code | ~/.claude/skills/ | プロジェクトの.claude/skills/ |
| Codex | ~/.agents/skills/ | プロジェクトの.agents/skills/ |
含まれるファイルはSKILL.mdの1つだけ。
配布元はaffaan-m/ECCで、ライセンスはMITです。
代表的な使い方は、新規プロジェクトの立ち上げ、既存プロジェクトの移行、テストとデプロイ設定の3つです。
TypeScriptでAPIサーバーを新しく作りたい。
Bunで始めて、テストとビルドの設定も入れて
この依頼では、Bun.serveを使ったHTTPサーバーと、bun:testで書いたテストファイルが用意されます。
依存はbun installで入り、ビルドはbun buildでdistに出す形です。
このNodeプロジェクトをBunへ移行する手順と、互換性の確認点を整理して
返ってくるのは、スクリプトの置き換え表と、bun installでロックファイルを作る手順です。
あわせて、ネイティブ拡張やNode固有の内部機能に頼る依存パッケージが確認点として挙がります。
bun testでテストを書き、Vercel向けのビルド設定を用意して
テストファイルと、bunVersionを指定したvercel.jsonがそろいます。
デプロイ時の手順は、bun install --frozen-lockfileとbun run buildを使う形です。
このスキルはBunのコマンドを使う手順書なので、手元にBun本体が入っている必要があります。
手順はBun 1.4.xが基準です。
CLIのフラグは版ごとに変わることがあるため、bun --versionで版を確かめてから使ってください。
BunのNode互換性は完全ではありません。
一部のネイティブ拡張、あまり使われないnode:の内部API、Node固有の内部に依存するパッケージは失敗することがあります。
**移行したら必ずテストを実行し、本番で頼る前に動作を確かめてください。
**
依存の操作にも注意が要ります。
bun auditはbun.lockにあるパッケージ名と版をレジストリに問い合わせます。
社内の非公開パッケージがある場合は、送信先を確認してください。
bun audit fixは、依存を更新してインストールし直すコマンドです。
そのため、ロックファイルやインストール済みのパッケージが変わります。
--isolateはファイルごとにグローバル環境を分けるだけで、プロセスやセキュリティのサンドボックスではありません。
Vercelの設定は、vercel.jsonの中身を確認してから反映してください。
スキル自体も、入れる前にSKILL.mdの中身を読んでおくと安心です。
いいえ。
ほとんどのパッケージは動きますが、互換性は100%ではありません。
ネイティブ拡張やNode固有の内部機能に頼るパッケージは、移行前に検証が必要です。
現在のBunの標準は、テキスト形式のbun.lockです。
古いバイナリ形式のbun.lockbも、移行のために読み込めます。
新しいプロジェクトで使うのはbun.lockです。
はい。
同じ依存を再現するためにbun.lockをコミットすることが、スキルのベストプラクティスに挙がっています。
Vercelでは--frozen-lockfileと組み合わせる形です。
手順はBun 1.4.xを基準に書かれています。
ほかの版で使うときは、インストールした版のヘルプやドキュメントで、フラグの対応状況を確かめてください。
bun-runtimeは、Bunでの実行・依存管理・ビルド・テスト・Vercel設定をひとまとめにした手順書です。
Nodeからの移行では、コマンドの置き換えと互換性の確認点をエージェントが整理してくれます。
ただし、移行後のテスト実行とvercel.jsonの確認だけは自分で行ってください。
詳しくはcccskillsのページを参照してください。
この記事は cccskills の読みもの「NodeからBunへの移行をbun-runtimeスキルでエージェントに任せる」の転載です。
スキルの詳細とインストール方法は cccskills の bun-runtime のページ にあります。