bun-runtime

Bun Runtime

概要

Bun は、高速なパッケージマネージャー、バンドラー、テストランナー、Node.js 互換 API を備えたオールインワンの JavaScript および TypeScript ランタイムです。別途コンパイルすることなく、TypeScript と JSX をネイティブに実行できます。

使用する場面： 高速なサーバーサイド JavaScript、TypeScript を中心とするプロジェクト、起動パフォーマンス向上のために Node.js を置き換える場合、組み込みの SQLite、パスワードのハッシュ化、ファイル I/O、HTTP サーバー、バンドル、外部ツールを使わないテスト。

使用しない場面： Node.js エコシステムとの完全な互換性が必要なプロジェクト（一部のネイティブモジュールは未対応）、実績を積んだ Node.js の安定性が必要な本番環境、またはランタイムを必要としないブラウザー専用コード。

クイックリファレンス

パターン	API	主なポイント
HTTP サーバー	Bun.serve({ routes, fetch })	ルートベース、静的／動的ルート、メソッドごとのハンドラー
ファイル読み込み	Bun.file(path)	遅延読み込みの BunFile（Blob）、.text()、.json()、.stream()
ファイル書き込み	Bun.write(dest, data)	string、Blob、Response、BunFile を受け付けます
SQLite	bun:sqlite の new Database(path)	同期クエリ、プリペアドステートメント、WAL モード
パスワードのハッシュ化	Bun.password.hash(pw)	デフォルトは Argon2id、bcrypt オプション、非同期／同期の両方に対応
パスワードの検証	Bun.password.verify(pw, hash)	ハッシュ形式からアルゴリズムを自動判別
バンドラー	Bun.build({ entrypoints, outdir })	ツリーシェイキング、コード分割、プラグイン、複数のターゲット
テストランナー	import { test, expect } from "bun:test"	Jest 互換、モック、スナップショット、ウォッチモード
パッケージのインストール	bun install	高速なロックファイル解決、npm 互換
パッケージの追加	bun add <pkg>	開発用には -d、グローバル用には -g
スクリプトの実行	bun run <script>	package.json のスクリプトまたはファイルを直接実行します
バイナリの実行	bunx <pkg>	npx と同様に、インストールせずに実行します
S3 クライアント	new S3Client(opts) / s3.file(key)	S3 互換ストレージ用の組み込みクライアント
HTML のインポート	import page from './index.html'	フルスタック：HTML をルートハンドラーとしてインポート

よくある間違い

間違い	正しいパターン
routes を使わず、fetch ハンドラーのみを使用する	静的／動的ルーティングには routes オブジェクトを使い（Bun v1.2.3 以降）、fetch はフォールバックとして使用します
Bun.write() に await を付け忘れる	Bun.write() は非同期のため、必ず await を付けます
Bun.file(path).text() を await なしで使用する	.text()、.json()、.arrayBuffer() はすべて Promise を返します
WAL モードを使わずに SQLite データベースを作成する	並行読み取りのために WAL を有効にします：db.exec("PRAGMA journal_mode = WAL")
CI で --frozen-lockfile を付けずに bun install を使う	再現可能な CI ビルドには bun install --frozen-lockfile を使います
Bun のテストで jest のグローバルをインポートする	@jest/globals や vitest ではなく、bun:test からインポートします
node_modules/.bin/ を直接使用する	bin パスを参照するのではなく、bunx または bun run を使います
失敗時に Bun.build() が例外をスローすると想定する	result.success の真偽値を確認します。エラーは result.logs に含まれます
Bun にデプロイする際に --target node を使用する	Bun 固有の最適化とバイトコードには --target bun を使います
リクエストハンドラーで同期的にパスワードをハッシュ化する	サーバーでは非同期版の await Bun.password.hash() を使います

委任

• プロジェクトのひな形作成：Explore エージェントを使用します
• パフォーマンスのプロファイリング：Task エージェントを使用します
• コードレビュー：code-reviewer エージェントに委任します

typescript-patterns スキルが利用可能な場合は、高度な TypeScript の型付けに関する質問をそのスキルに委任してください。

参考資料

• ランタイム API：Bun.serve()、Bun.file()、SQLite、パスワードハッシュ化、ユーティリティ
• パッケージ管理：インストール、追加、削除、ワークスペース、ロックファイル
• バンドラー：Bun.build()、エントリーポイント、プラグイン、ツリーシェイキング
• テスト：bun:test、アサーション、モック、スナップショット、ライフサイクルフック