bun

Bun スキルリファレンス

製品概要

Bun は Zig で書かれた、JavaScript ランタイム、パッケージマネージャー、バンドラー、テストランナーを統合したものです。Node.js、npm、esbuild、Jest を、1 つの高速なバイナリに置き換えます。主なファイル：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 と 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 をご覧ください