bun

Bun スキルリファレンス

製品概要

Bun は、Zig で記述された統合 JavaScript ランタイム、パッケージマネージャー、バンドラー、テストランナーです。Node.js、npm、esbuild、Jest を単一の高速なバイナリに置き換えます。主要なファイル：bunfig.toml（設定）、bun.lock（ロックファイル）、package.json（プロジェクトのメタデータ）。主なコマンド：bun run、bun install、bun build、bun test。Bun は起動時の速度が Node.js の 4 倍、インストール速度が npm の 25 倍です。詳しいドキュメントについては https://bun.com/docs をご覧ください。

使用する場面

次の場合に Bun を使用します。

• スクリプトの実行：コンパイル手順なしで TypeScript／JavaScript ファイルを直接実行します（bun run file.ts）。
• 依存関係の管理：npm／yarn／pnpm より高速にパッケージをインストール、追加、削除、更新します（bun install、bun add）。
• コードのバンドル：bun build を使用して、ブラウザーまたはサーバー向けに JavaScript／TypeScript をビルドします。
• テスト：組み込みのテストランナーで Jest 互換のテストを実行します（bun test）。
• フルスタックアプリのビルド：サーバーコードとクライアントコードをまとめて単一の実行可能ファイルにバンドルします。
• モノレポのワークフロー：ワークスペースとフィルタリングを使用して、複数のパッケージを管理します。
• Node.js の置き換え：Node.js 互換のコードを、より優れたパフォーマンスで実行します。

型チェック（別途 tsc を使用）、型宣言の生成、またはネイティブモジュールで厳密な Node.js 互換性が必要なプロジェクトには Bun を使用しないでください。

クイックリファレンス

基本コマンド

タスク	コマンド	メモ
TypeScript ファイルを実行	bun run file.ts	オンザフライでトランスパイルします。短縮形では run を省略できます。
パッケージスクリプトを実行	bun run dev	package.json のスクリプトを実行します。
依存関係をインストール	bun install	bun.lock ロックファイルを作成します。
パッケージを追加	bun add react	dependencies に追加します。開発用には -d を使用します。
パッケージを削除	bun remove react	package.json と node_modules から削除します。
テストを実行	bun test	*.test.ts、*.spec.ts ファイルを自動的に検索します。
バンドルをビルド	bun build ./src/index.ts --outdir ./dist	ツリーシェイキングを行ってバンドルします。必要に応じて縮小できます。
ウォッチモード	bun --watch run file.ts	ファイルの変更時に再実行します。
プロジェクトを作成	bun init	テンプレートを使って新しいプロジェクトを作成します。

設定ファイル：bunfig.toml

プロジェクトのルート、または ~/.bunfig.toml（グローバル）に配置します。必須ではありませんが、カスタマイズに役立ちます。

[install]
dev = true                    # Install devDependencies
optional = true               # Install optionalDependencies
peer = true                   # Install peerDependencies
linker = "hoisted"           # "hoisted" or "isolated" (pnpm-style)
saveTextLockfile = true      # Use text bun.lock instead of binary

[serve]
port = 3000                  # Default port for Bun.serve()

[test]
root = "."                   # Test root directory
coverage = false             # Enable coverage reporting
timeout = 5000               # Per-test timeout in ms
preload = ["./setup.ts"]     # Scripts to run before tests

[run]
shell = "system"             # "system" or "bun" (Windows defaults to "bun")
bun = true                   # Auto-alias node to bun in scripts

対応ファイル形式

Bun は .js、.jsx、.ts、.tsx、.json、.jsonc、.toml、.yaml、.html、.css、.wasm、.node をネイティブに処理します。設定は不要です。インポートして使用するだけです。

主な Bun API

API	用途	例
Bun.serve()	HTTP サーバーを起動	Bun.serve({ port: 3000, fetch: handler })
Bun.file()	ファイルの読み書き	await Bun.file("path.txt").text()
Bun.write()	ディスクに書き込み	await Bun.write("out.txt", data)
Bun.build()	コードをバンドル	await Bun.build({ entrypoints, outdir })
Bun.Transpiler	コードをトランスパイル	new Bun.Transpiler({ loader: "tsx" })
Bun.spawn()	子プロセスを実行	Bun.spawn(["ls", "-la"])

選択の指針

Hoisted linker と Isolated linker の使い分け

シナリオ	使用するもの	理由
新しいモノレポ／ワークスペース	isolated	ファントム依存関係を防止し、分離を強化します
新しい単一パッケージプロジェクト	hoisted	従来の npm の動作で、よりシンプルです
既存のプロジェクト（v1.3.2 より前）	hoisted	下位互換性
pnpm からの移行	isolated	pnpm の方式に合致します

bunfig.toml で設定します：linker = "isolated" または CLI 経由で設定します：bun install --linker isolated

bun build と bun run の使い分け

ユースケース	ツール	理由
TypeScript を直接実行する	bun run	高速なトランスパイルで、出力ファイルは不要です
本番環境向けに準備する	bun build	ミニファイ、ツリーシェイキング、バンドル
単一の実行ファイルを配布する	bun build --compile	スタンドアロンバイナリを作成します
開発サーバー	bun run + Bun.serve()	ホットリロード、高速な反復開発

テストで --concurrent を使う場面

シナリオ	--concurrent を使用	理由
独立した非同期テスト	はい	並列実行によりテストスイートが高速化します
状態を共有するテスト	いいえ	順序に依存するテストには test.serial() を使用します
データベース／API テスト	場合によります	テストが互いに干渉しない場合に限ります
ユニットテスト	はい	通常は安全で、より高速です

ワークフロー

1. プロジェクトを初期化する

bun init my-app
cd my-app

テンプレートとして Blank、React、または Library を選択します。package.json、tsconfig.json、.gitignore が作成されます。

2. 依存関係をインストールする

bun install

package.json を読み取り、パッケージをダウンロードして、bun.lock を作成します。npm よりもはるかに高速です。

3. パッケージを追加する

bun add react
bun add -d @types/react typescript

package.json と bun.lock が自動的に更新されます。

4. コードを記述して実行する

# Create index.ts
echo "console.log('Hello Bun!')" > index.ts

# Run it
bun run index.ts

Bun は TypeScript をオンザフライでトランスパイルするため、ビルド手順は不要です。

5. HTTP サーバーを作成する

// server.ts
const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello!");
  },
});
console.log(`Listening on ${server.url}`);

bun run server.ts

6. テストを記述する

// math.test.ts
import { test, expect } from "bun:test";

test("2 + 2 = 4", () => {
  expect(2 + 2).toBe(4);
});

bun test

すべての *.test.ts ファイルを自動的に検索して実行します。

7. 本番環境向けにバンドルする

bun build ./src/index.ts --outdir ./dist --minify

最適化されたバンドルを dist/ に出力します。出力形式を制御するには --target browser|node|bun を使用します。

8. スタンドアロン実行ファイルを作成する

bun build ./cli.ts --outfile mycli --compile
./mycli

コードと Bun ランタイムを単一の実行ファイルにバンドルするため、依存関係は不要です。

よくある注意点

• ライフサイクルスクリプトはデフォルトで無効：Bun はセキュリティ上の理由から postinstall スクリプトを実行しません。実行を許可するには、信頼できるパッケージを package.json の trustedDependencies に追加します。
• bun run と bun <script> の違い：同じ名前の組み込み Bun コマンドがある場合は、package.json のスクリプトを実行するために bun run <script> を明示的に使用します。
• ウォッチモードフラグの位置：bun run file.ts --watch ではなく、bun --watch run file.ts を使用します。ファイル名より後ろのフラグはスクリプト自体に渡されます。
• Bun グローバルに関する TypeScript エラー：@types/bun をインストールし、tsconfig.json の compilerOptions に "lib": ["ESNext"] を追加します。
• ロックファイル形式：Bun v1.2+ では、デフォルトでテキスト形式の bun.lock が使用されます（バイナリ形式の bun.lockb ではありません）。バージョン管理にコミットしてください。
• CI では自動インストールが無効：予期しないパッケージのダウンロードを防ぐため、本番環境では bunfig.toml に install.auto = "disable" を設定します。
• Node.js との互換性：Bun は Node.js API の大部分を実装していますが、すべてではありません。Node.js 固有のコードに依存する前に、node: モジュールのサポート状況をドキュメントで確認してください。
• バンドラーは常にバンドルする：esbuild とは異なり、bun build はデフォルトで常にバンドルします。バンドルせずに個別のファイルをトランスパイルするには、Bun.Transpiler を使用します。
• バンドラーは型チェックを行わない：bun build は型チェックを行いません。型を検証するには、別途 tsc --noEmit を実行します。
• ピア依存関係はデフォルトでインストールされる：npm とは異なり、Bun はピア依存関係を自動的にインストールします。無効にするには、bunfig.toml に peer = false を設定します。

検証チェックリスト

Bun を使用した作業を提出する前に、次の項目を確認してください。

• bun install を実行し、依存関係がエラーなく解決されることを確認する
• bun run <script> を実行し、メインのエントリーポイントをテストする
• bun test を実行し、すべてのテストが成功することを確認する
• bun build を実行し、outdir に出力ファイルが存在することを確認する
• bun.lock がバージョン管理にコミットされていることを確認する（.gitignore に追加されていないこと）
• bunfig.toml に削除すべき環境固有の設定がないか確認する
• node_modules フォルダーがコミットされていないことを確認する（.gitignore に追加してください）
• デプロイ用にビルドする場合は、--production フラグを付けてテストする：bun install --production
• TypeScript ファイルに型エラーがないことを確認する：bun run tsc --noEmit（tsc がインストールされている場合）
• ESM プロジェクトでは、package.json に "type": "module" が設定されていることを確認する

リソース

包括的なナビゲーション：https://bun.com/docs/llms.txt — Bun ドキュメントのページごとの一覧です。

重要なページ：

1. Bun ランタイム — ファイルやスクリプトの実行、ランタイムの管理
2. パッケージマネージャー — パッケージのインストール、追加、削除、依存関係の管理
3. バンドラー — JavaScript/TypeScript を本番環境向けにバンドル
4. テストランナー — Jest 互換のテストの作成と実行
5. bunfig.toml — Bun の動作の設定

---

追加のドキュメントやナビゲーションについては、https://bun.com/docs/llms.txt を参照してください。