本文へ移動
cccskills
bun-runtime開発

NodeからBunへの移行をbun-runtimeスキルでエージェントに任せる

cccskills 編集部読了 約 10 分

この記事の結論

こんな人に
JavaScript・TypeScriptの開発でBunを使い始めたい人や、既存のNodeプロジェクトをBunへ移したい開発者
入れると
  • 「Bunへ移行して」と頼むと、nodeやnpmのコマンドがBunのコマンドに置き換わる
  • テストはbun testのJestに似た書き方でそろい、CI向けの並列・分割実行も頼める
  • Vercelでは、bunVersionの指定とロックファイルを固定したビルド手順まで任せられる
向かない人
Node前提の古いツールや、Bunで既知の問題がある依存パッケージに頼るプロジェクト

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.jsbun run script.jsまたはbun script.js
npm installbun install
npm run devbun run dev
npxでの単発実行bun x

テストはbun:testからexpectとtestを読み込む形で書かれます。APIはJestに似ているため、書き方を一から覚え直す必要はありません。

bun-runtimeでできること

bun-runtimeは、Bunをランタイム(プログラムを動かす実行環境)、パッケージマネージャー、バンドラー、テストランナーの4役で使うための手順書です。実行から配布用ビルドまでを1つの道具にそろえられるので、エージェントに同じ流儀で作業させられます。

BunとNodeの使い分け

スキルには、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でのテスト作成・修正

全テストを実行するコマンドはbun testです。--watchを付ければ、ファイルの変更に合わせて再実行されます。CI向けには、Bun 1.4で使えるオプションも整理されています。

オプション用途
--changed変更の影響を受けるテストだけを実行する
--parallelワーカープロセスで並列に実行する
--shard=<n>/<count>CIでテストを分割して実行する
--isolateファイルごとに新しいグローバル環境で実行する

Vercelのビルドとデプロイ設定

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の中身を読んでおくと安心です。

まとめ

bun-runtimeは、Bunでの実行・依存管理・ビルド・テスト・Vercel設定をひとまとめにした手順書です。Nodeからの移行では、コマンドの置き換えと互換性の確認点をエージェントが整理してくれます。

ただし、移行後のテスト実行とvercel.jsonの確認だけは自分で行ってください。詳しくはcccskillsのページを参照してください。

よくある質問

Bunに移せばNodeのパッケージはすべて動きますか
いいえ。ほとんどのパッケージは動きますが、互換性は100%ではありません。ネイティブ拡張やNode固有の内部機能に頼るパッケージは、移行前に検証が必要です。
古いbun.lockbはどうなりますか
現在のBunの標準は、テキスト形式のbun.lockです。古いバイナリ形式のbun.lockbも、移行のために読み込めます。新しいプロジェクトで使うのはbun.lockです。
ロックファイルはコミットすべきですか
はい。同じ依存を再現するためにbun.lockをコミットすることが、スキルのベストプラクティスに挙がっています。Vercelでは--frozen-lockfileと組み合わせる形です。
Bun 1.4以外の版でも使えますか
手順はBun 1.4.xを基準に書かれています。ほかの版で使うときは、インストールした版のヘルプやドキュメントで、フラグの対応状況を確かめてください。

このスキルを試す

bun-runtime の入れ方とインストールコマンドは、cccskills のスキルページにまとめてあります。

この記事は、公開されている SKILL.md と cccskills の紹介文をもとに AI(Claude)が下書きし、cccskills 編集部の方針に沿って推敲・公開しています。正確な仕様はスキルのページで原文を確認してください。

他の記事