bun-runtime

Bun Runtime

Bun は JavaScriptCore（Safari のエンジン）上に構築された、高速なオールインワン JavaScript ランタイムです。Linux では Node.js より起動が 4 倍速くなります。

クイックスタート

# Run a file
bun run index.ts
bun index.ts  # shorthand

# Run with watch mode
bun --watch run index.ts

# Run package.json script
bun run dev

# Run with hot reloading
bun --hot run server.ts

主な CLI フラグ

フラグ	目的
--watch	ファイルの変更時に再起動します
--hot	ホットモジュール置換（状態を保持）
--smol	メモリ使用量を削減します（ガベージコレクションが遅くなります）
--inspect	デバッガーを有効にします
--preload	実行前にモジュールを読み込みます
--env-file	特定の .env ファイルを読み込みます
-e, --eval	コード文字列を評価します

ファイルの実行

Bun は TypeScript と JSX を実行時にトランスパイルします。

bun run index.js
bun run index.ts
bun run index.jsx
bun run index.tsx

重要：Bun のフラグは bun の直後に指定してください。

bun --watch run dev    # Correct
bun run dev --watch    # Wrong - flag passed to script

package.json スクリプト

# Run script
bun run dev
bun dev  # shorthand (if no Bun command conflicts)

# List available scripts
bun run

# Run with Bun instead of Node
bun run --bun vite

Bun はライフサイクルフック（preclean、postclean など）に対応しています。

ウォッチモードとホットリロード

モード	フラグ	動作
ウォッチ	--watch	変更時にプロセス全体を再起動します
ホット	--hot	モジュールを置き換え、状態を保持します

# Watch mode - full restart
bun --watch run server.ts

# Hot reloading - preserves connections/state
bun --hot run server.ts

環境変数

Bun は .env ファイルを自動的に読み込みます。

# Loads automatically: .env, .env.local, .env.development
bun run index.ts

# Specify env file
bun --env-file .env.production run index.ts

# Disable auto-loading
# In bunfig.toml: env = false

コード内でのアクセス：

const apiKey = process.env.API_KEY;
const bunEnv = Bun.env.NODE_ENV;

利用可能なグローバル

グローバル	提供元	備考
Bun	Bun	メイン API オブジェクト
Buffer	Node.js	バイナリデータ
process	Node.js	プロセス情報
fetch	Web	HTTP リクエスト
Request/Response	Web	HTTP 型
WebSocket	Web	WebSocket クライアント
crypto	Web	暗号化
console	Web	ロギング
__dirname	Node.js	現在のディレクトリ
__filename	Node.js	現在のファイル

プリロードスクリプト

メインスクリプトの前にモジュールを読み込みます。

bun --preload ./setup.ts run index.ts

または、bunfig.toml に記述します。

preload = ["./setup.ts"]

用途：ポリフィル、グローバル設定、インストルメンテーション。

標準入力からの実行

# Pipe code to Bun
echo "console.log('Hello')" | bun run -

# Redirect file
bun run - < script.js

ワークスペースとモノレポ

# Run script in specific packages
bun run --filter 'pkg-*' build

# Run in all workspaces
bun run --filter '*' test

デバッグ

# Start debugger
bun --inspect run index.ts

# Wait for debugger connection
bun --inspect-wait run index.ts

# Break on first line
bun --inspect-brk run index.ts

Chrome DevTools または VS Code から接続します。

よくあるエラー

エラー	原因	対処方法
Cannot find module	依存関係がありません	bun install を実行します
Top-level await	async の外で await を使用しています	async 関数で囲むか、.mts を使用します
--watch not working	フラグの位置が間違っています	run の前にフラグを指定します

リファレンスを読み込むタイミング

次の場合は references/bunfig.md を読み込みます。

• bunfig.toml を設定するとき
• テスト設定を行うとき
• パッケージマネージャーの動作を設定するとき
• JSX オプションを設定するとき

次の場合は references/cli-flags.md を読み込みます。

• CLI フラグの全リファレンスが必要なとき
• ランタイムの高度なオプションを設定するとき
• デバッグを設定するとき

次の場合は references/module-resolution.md を読み込みます。

• インポートエラーをトラブルシューティングするとき
• パスエイリアスを設定するとき
• Bun の解決アルゴリズムを理解するとき