bun-cli

Bun CLI

Bun は、JavaScript／TypeScript のオールインワンランタイム、パッケージマネージャー、バンドラー、テストランナー、型チェッカー（v1.4.3+）、フォーマッター（v1.4.4+）です。Bun は TypeScript をネイティブに実行します。bun file.ts と直接実行でき、コンパイル手順も tsc も ts-node も不要です。bun check は tsc --noEmit に、bun fmt は prettier --write に代わります。Bun プロジェクトでは、常に node、npm、npx、yarn、pnpm ではなく bun を使用してください。

Bun v1.4.4 で検証済み（2026-10-22）。機能には、導入されたバージョン（v1.4+、v1.4.1+、v1.4.2+、v1.4.3+、v1.4.4+）を記載しています。リリースで既存の動作が変更された場合は、古いプロジェクトでもこのスキルが正しく機能するよう、両方の動作を記載しています。バージョンが記載された項目を利用する前に、bun --version を実行してください。

バージョンガイド：各 1.4.x リリースでの変更点

リリース	追加機能	既存プロジェクトへの変更	アップグレードするタイミング
1.4.0 (2026-08-20)	bun audit fix、bun dedupe、bun prune、bun why、bun pm licenses / diff、add / remove / update での --filter、--catalog、bun test --timings、--react-compiler、--asset	bun.lock v2 / v3（Bun 1.3 では v3 を読み込めません）、厳密な TOML 構文に従う bunfig.toml、bun update による推移的依存関係の移動、resetAllMocks() による実装の削除	1.4 のツール群が必要な場合は、まず CI の Bun バージョン固定設定と bunfig.toml をすべて確認してください
1.4.1 (2026-09-04)	--offline / --prefer-offline、自己完結型ワークスペース、--min-chunk-size、--bytecode-depth、パイプからの --env-file、--no-ffi-cc	分割チャンクがより少なく小さくなり、modulepreload リンクが追加されます（ビルドのスナップショットが変わります）	このバージョンは目標にしないでください。バンドラーが入れ子の var を let に改名することがあり、Elysia のバンドルが読み込みに失敗します。1.4.2 以降にしてください
1.4.2 (2026-09-05)	なし（バグ修正リリース）	--	1.4.1 を使用している場合、または bun install が range end index out of range でパニックになる場合
1.4.3 (2026-10-10)	bun check / --check、--bytecode-order、--compile-jit-policy、[hash9]～[hash13]	インストール時に配置するものだけがキャッシュされるようになります（--offline キャッシュには、すべてを含むウォームアップインストールが必要です）。--disallow-code-generation-from-strings が適用され、Bun.build({ tsconfig }) が尊重され、--coverage-reporter を指定すると --coverage も有効になります	tsc を使わずに型チェックしたい場合、または大規模な --splitting ビルドが Multiple files share the same output path で失敗する場合
1.4.4 (2026-10-22)	bun fmt、bun pm fetch、bun pm cache pack / unpack / prune、bun publish --recursive、packageExtensions、link:./path、--libc、bun check --no-script、Yarn Berry ロックファイルの移行	不明なパッケージマネージャーのフラグは終了コード 1 を返し、npm／Yarn／pnpm のフラグは変換されます。pnpm 形式のピア依存関係解決、より厳格なカバレッジ集計、hoisted リンカーによる package.json から削除された依存関係の除去	組み込みフォーマッター、Berry の移行、レジストリの一時的な障害に耐える bun install の再試行、または解決済みの bun install の問題 133 件の修正が必要な場合は、CI を一度実行してフラグエラーと coverageThreshold の低下を確認してください

常に最新のパッチバージョンを使用してください。 各パッチは、それ以前のバージョンのリグレッションを修正しています（references/migration-1.4.md のリリースごとの一覧を参照）。そのため、既知の良好な 1.4.x として古いバージョンに固定すると、既知のバグが残ります。プロジェクトをアップグレードする前に、その間の各リリースについて「既存プロジェクトへの変更」列を確認してください。これらの変更により、アップグレード時に修正が必要になる場合があります。

バージョンを確認してから、Bun のドキュメントを確認する

bun <command> --help はフラグに関する正式な情報であり、インストール済みバイナリと常に一致します。フラグの情報がここにある表と異なる場合は、こちらを優先してください。

フラグ以外の情報については、bun-types または @types/bun がインストールされているプロジェクトであれば、Bun に付属する完全なドキュメントを bun-types 内で参照できます。ドキュメントのバージョンはランタイムと一致しています。

node_modules/bun-types/docs/pm/**/*.mdx        # install, lockfile, workspaces, catalogs, linkers
node_modules/bun-types/docs/test/**/*.mdx      # test runner
node_modules/bun-types/docs/bundler/**/*.mdx   # bun build, executables, loaders, plugins
node_modules/bun-types/docs/runtime/bunfig.mdx
node_modules/bun-types/CLAUDE.md             # Bun's own agent rules

1. @types/bun ではなく bun-types に依存してください。 bun-types はすべての Bun リリースに付属し、ドキュメントと型定義の両方を含みます。@types/bun はリリースへの追従が遅く、1 日以上遅れることもよくありますが、bun init はこれを latest として追加するため、最新の API が bun check で拒否されます（TS2339、TS2353）。@types/bun と並べて bun-types を追加しても、修正されるのはドキュメントのパスだけです。型チェックでは引き続き @types/bun のネストされた固定バージョンのコピーが使われます。両方を切り替えてください。

   bun remove @types/bun
   bun add -d bun-types@$(bun --version)   # then "types": ["bun-types"] in tsconfig.json
   

   どちらを信頼する前にも、bun --version と node_modules/bun-types/package.json を照合してください。

2. 明示的なパスで開いてください。 グローバル仮想ストアが有効な場合、node_modules/bun-types はシンボリックリンクです。そのため、find node_modules -name '*.mdx' と rg <pattern> node_modules は何も返しません。find node_modules/bun-types/docs -name '*.mdx' なら機能します。

3. node_modules/ 内は編集しないでください。 グローバルストアでは、マシン上のすべてのプロジェクトが同じ inode を共有します。bun patch を使用してください。

4. インストールされていない場合は？ 同じパスをオンラインでも参照できます。docs/pm/lockfile.mdx は https://bun.com/docs/pm/lockfile です。

5. ドキュメントがリリースに先行する場合があります。 bun-types 1.4.4 には docs/lint/** と runtime/bunfig.mdx の [lint] セクションが含まれますが、bun lint が使えるのは canary ビルドのみです。安定版の 1.4.4 では bun lint は bun run lint として扱われるため、プロジェクトの lint スクリプトが実行されるか、Script not found "lint" というエラーになります。プロジェクトのリンターを引き続き使用してください。

タスク	ドキュメントのパス（node_modules/bun-types/docs/ 以下）
インストールの動作、ロックファイル、リンカー	pm/cli/install.mdx、pm/lockfile.mdx、pm/isolated-installs.mdx、pm/global-store.mdx
ワークスペース、カタログ、フィルター、オーバーライド	pm/workspaces.mdx、pm/catalogs.mdx、pm/filter.mdx、pm/overrides.mdx、pm/package-extensions.mdx（v1.4.4 以降）
レジストリ、認証、ライフサイクルスクリプト	pm/scopes-registries.mdx、pm/npmrc.mdx、pm/lifecycle.mdx
型チェック（bun check、--check）	runtime/check.mdx
フォーマット（bun fmt、v1.4.4 以降）	format/index.mdx、guides/format/migrate-from-prettier.mdx、guides/format/migrate-from-oxfmt.mdx
テストランナー	test/index.mdx、test/discovery.mdx、test/configuration.mdx、test/code-coverage.mdx、test/reporters.mdx、test/mocks.mdx
バンドラー、実行可能ファイル、ローダー	bundler/index.mdx、bundler/executables.mdx、bundler/loaders.mdx、bundler/plugins.mdx
設定	runtime/bunfig.mdx
npm/yarn/pnpm からの移行	guides/install/from-npm-install-to-bun-install.mdx

Bun プロジェクトの検出

次のいずれかが存在するプロジェクトは、Bun を使用しています。

• プロジェクトルートに bun.lock または bun.lockb がある
• プロジェクトルートに bunfig.toml がある
• package.json に bun フィールドがある（例："bun": { "install": { ... } }）
• パッケージマネージャーフィールドがある："packageManager": "bun@..."
• bunfig.toml に [run] bun = true がある（すべてのスクリプトで Bun ランタイムを強制）

重要なルール

Bun プロジェクトでは、必ずすべてに bun を使用してください。 node、npm、npx、yarn、pnpm に切り替えてはいけません。これにより、互換性の問題、不要な再試行、Node.js/npm が Bun 固有の機能（ワークスペースプロトコル、ロックファイル形式、trustedDependencies など）を理解できないことによる不可解なエラーを避けられます。

• ファイルの実行：bun file.ts（node file.ts ではありません）
• スクリプトの実行：bun run dev（npm run dev ではありません）
• バイナリの実行：bunx tool（npx tool ではありません）
• パッケージのインストール：bun add pkg（npm install pkg ではありません）
• テストの実行：bun test（npx jest や node --test ではありません）
• 型チェック：bun check（tsc --noEmit ではありません。v1.4.3 以降）
• フォーマット：bun fmt（prettier --write . ではありません。v1.4.4 以降）

読み取り専用コマンド（安全、副作用なし）

コマンド	目的
bun --version	ランタイムのバージョン
bun info <pkg>	パッケージのメタデータ、利用可能なバージョン
bun info <pkg> versions	公開済みの全バージョンを一覧表示
bun pm ls	インストール済みパッケージを一覧表示（エイリアス：bun list）
bun pm ls --all	すべて（推移的依存関係を含む）を一覧表示
bun pm ls --trusted	ライフサイクルスクリプトの実行が許可されているパッケージのみを一覧表示（v1.4+）
bun pm ls <name>	あるパッケージのインストール済みコピーをすべて表示（v1.4.4+）
bun pm hash	ロックファイルのハッシュを出力
bun pm cache	キャッシュディレクトリを表示
bun pm bin	binディレクトリを出力（グローバルの場合は-g）
bun pm licenses	依存関係をライセンス別にグループ化して一覧表示（v1.4+；--json、--prod）
bun pm diff <pkg>	パッケージの2つのバージョン間の差分を表示（v1.4+）
bun pm untrusted	ライフサイクルスクリプトの実行がブロックされたパッケージを一覧表示
bun why <pkg>	パッケージがインストールされている理由を説明
bun outdated	古くなった依存関係を確認
bun audit	セキュリティ脆弱性を監査
bun dedupe --check	ロックファイルに削除可能な重複がある場合、終了コード1で終了（v1.4+）
bun prune --dry-run	node_modulesから削除されるものを表示（v1.4+）
bun prune --check	node_modulesに削除可能なパッケージがある場合、終了コード1で終了。何も削除しません（v1.4.4+）
bun install --frozen-lockfile --dry-run	bun.lockとpackage.jsonに不一致がある場合、終了コード1で終了。何もインストールしません。v1.4.4より前では、--dry-runでもプロジェクトのライフサイクルスクリプトが実行されていました
bun test	テストスイートを実行
bun --check	プロジェクト全体の型チェックを行って終了。ファイルの書き込みやスクリプトの実行は行いません（v1.4.3+）。package.jsonでcheckスクリプトが定義されていない場合、bun checkも同じ処理を行います。定義されている場合は、そのスクリプトを実行します。bun check --no-script（v1.4.4+）はスクリプトを実行しません
bun fmt --no-script --check	フォーマットが必要なファイルを一覧表示し、該当するファイルがあれば終了コード1で終了。何も書き込みません（v1.4.4+）。--no-scriptを指定しない場合、package.jsonのfmtスクリプトが代わりに実行されます
bun run lint	リンターを実行（プロジェクト固有）
bun run check-types	型チェック（プロジェクト固有）

参考：Claude Code／OpenCodeの設定で使える、コピー＆ペースト用のBash(command:*)パターンについては、references/allowlist.mdを参照してください。

npm/npx/nodeからBunへの置き換え

npm/npx/node	Bunでの同等コマンド
npm install	bun install
npm install pkg	bun add pkg
npm install -D pkg	bun add -d pkg
npm install -g pkg	bun add -g pkg
npm uninstall pkg	bun remove pkg
npm update	bun update
npm run script	bun run script
npx command	bunx command
node file.js	bun file.js
node --watch file.js	bun --watch file.js
npm test	bun test
tsc --noEmit	bun check (v1.4.3+)
prettier --write .	bun fmt --no-script (v1.4.4+；package.jsonにfmtスクリプトがある場合、通常のbun fmtはそのスクリプトを実行します)
prettier --check .	bun fmt --no-script --check (v1.4.4+)
npm pack	bun pm pack
npm publish	bun publish
npm info pkg	bun info pkg
npm outdated	bun outdated
npm audit	bun audit
npm link	bun link

主な動作の違い

• npm run のプレフィックスは不要です：bun run dev だけでなく、bun dev でも実行できます（スクリプトを直接実行）
• --bun フラグ：シバンに node を指定しているスクリプトに対して、Node.js ではなく Bun ランタイムを強制します。bunfig.toml で [run] bun = true を設定すると、これをデフォルトにできます
• ロックファイル：Bun は bun.lock（テキスト形式、v1.2 以降）または bun.lockb（バイナリ形式、レガシー）を使用します。新しいプロジェクトではテキスト形式のロックファイルがデフォルトです
• ワークスペースコマンド：--filter フラグを使用します：bun --filter 'pkg-name' add dep
• ライフサイクルスクリプト：Bun はセキュリティ上の理由から、デフォルトでライフサイクルスクリプトを無視します。postinstall などを必要とするパッケージを許可リストに登録するには、package.json の trustedDependencies を使用します
• 他のパッケージマネージャーのフラグ（v1.4.4 以降）：install、ci、add、remove、update は、Bun に同等の機能がある npm／Yarn／pnpm のフラグ（--save-dev、--immutable、--shamefully-hoist、--only=production）に変換し、サポートされていないフラグは値とともに無視します（--network-timeout 100000）。また、どのパッケージマネージャーにも存在しないフラグを指定すると、タイプミスも含めて 終了コード 1 で終了します（--frozen-lockfil）。Bun 1.4.3 では、これら 3 つすべてが正しく動作しませんでした。bun add --save-dev x は dependencies に書き込み、--network-timeout 100000 は 100000 というパッケージをインストールしようとし、タイプミスの場合は通常のインストールが実行されていました

パッケージ管理

依存関係のインストール

bun install                    # Install all from package.json
bun install --frozen-lockfile  # CI mode: fail if lockfile needs update
bun install --no-save          # Install without updating package.json
bun install --production       # Skip devDependencies
bun install --dry-run          # Show what would be installed; runs no scripts as of v1.4.4
bun install --offline          # No network at all; every package must already be cached (v1.4.1+)
bun install --prefer-offline   # Cached metadata regardless of age; download only what is missing (v1.4.1+)
bun install --env-file ci.env  # Env for lifecycle scripts; every package manager command takes it (v1.4.4+)
bun install --libc musl        # Native packages for another libc, e.g. an Alpine image from glibc (v1.4.4+)
bun pm fetch                   # Download every locked package into the cache; no node_modules, no scripts (v1.4.4+)

--offline は、~/.bun/install/cache を復元する CI ジョブやネットワークに接続できないマシンに適しています。パッケージが見つからない場合は、その名前を示して失敗します（no cached manifest for 'left-pad'）。--prefer-offline は古さの確認を省略しますが、キャッシュされていないパッケージは引き続き取得します。どちらも bunfig.toml で設定できます：[install] offline = true と [install] prefer = "offline"。

1.4.3 で変更――インストール時に、配置するものだけをキャッシュするようになりました。 ロックファイルがない場合、bun install と bun add は node_modules に配置されない tarball をダウンロードしなくなりました。対象には、--production または --omit で除外されたグループ、他のプラットフォーム向けのオプションパッケージ、バンドルされた依存関係が含まれます。bun install --production でキャッシュを準備した後に、すべてを対象とする --offline インストールを実行すると、"left-pad" is not in the cache というエラーになります。オフライン用のキャッシュは、同じプラットフォーム上で、少なくとも同じパッケージを配置するインストールによって準備してください。

1.4.4 で変更――依存関係の解決。 ピア依存関係は pnpm と同様に解決されます。パッケージより上位の階層にピア依存関係を提供するものがない場合、そのパッケージにはピア依存関係の範囲内のバージョンが割り当てられ、同じピア依存関係を持つすべてのパッケージで共有されます。Bun 1.4.3 は、無関係なパッケージがインストールしたバージョンを割り当てていました。たとえば、@modelcontextprotocol/sdk の隣に express@5 がある場合、@remix-run/express にも ^4.20.0 というピア依存関係の範囲に合わない express@5 が割り当てられていました。1.4.4 では、@remix-run/express 用に express@4 がネストされます。すでに bun.lock にあるバージョンは維持されます。ピア依存関係を再解決するには、パッケージを削除して再追加してください。その他の新機能として、Yarn Berry の yarn.lock ファイルがすべてのバージョン固定を保持したまま bun.lock に移行されます（1.4.3 で移行できたのは Yarn v1 のみでした）。Linux でのインストールでは、別の libc 向けにビルドされたオプションのネイティブパッケージがスキップされます（--libc '*' を指定すると両方をインストールします）。また、レジストリへのリクエストが失敗すると、50 ms から始まる指数バックオフで再試行されます（約 1.5 秒を超える障害では BUN_CONFIG_HTTP_RETRY_BACKOFF=250 を指定してください）（リリースノート）。

パッケージの追加／削除

bun add pkg                    # Add to dependencies
bun add pkg@version            # Add specific version
bun add -d pkg                 # Add to devDependencies (--dev)
bun add -D pkg                 # Same as -d
bun add --optional pkg         # Add to optionalDependencies
bun add --peer pkg             # Add to peerDependencies
bun add -g pkg                 # Install globally
bun add --exact pkg            # Pin exact version (no ^)
bun add pkg --filter api       # Add to one workspace from the repo root (v1.4+)
bun add pkg --catalog          # Add to the root catalog, depend on it as "catalog:" (v1.4+)
bun add --save-prod pkg        # Move back to dependencies from another group (v1.4.4+)
bun remove pkg                 # Remove package

1.4.4 で変更： bun add -d、--optional、--peer、--save-prod は、別のグループにすでに登録されているパッケージを移動するようになりました（以前は元のグループに残っていました）。--exact はインストール済みのバージョンを固定します（is-number@7 は 7 ではなく 7.0.0 と書き込みます）。非推奨の直接依存関係がある場合は、warn: deprecated <pkg>@<version>: <message> と表示されます。リリースノートによると、解決時には npm と同様に、非推奨ではないバージョンが優先されます。

1.4 で変更： bun add、bun remove、bun update は --filter を受け付けるようになり、bun install <pkg> --filter x はルートではなくワークスペース x を編集するようになりました。デフォルトカタログにパッケージがすでに登録されているワークスペースでは、単純な bun add <pkg> により catalog: が書き込まれます。--filter 'web...' は web とその依存先すべてを選択し、'...web' は web に依存するすべてを選択します。

更新と検査

bun update                     # Update all packages within package.json ranges
bun update pkg                 # Update every copy of pkg, transitive ones included (v1.4+)
bun update '@types/*' --latest # Patterns; --latest ignores the declared range
bun update --recursive         # Update every workspace and write each package.json (v1.4+)
bun update --filter 'pkg-*' --filter '!pkg-c'   # Repeatable; ! excludes (v1.4+)
bun update --depth 0           # Direct dependencies only; transitive ones stay locked unless a new range excludes them (v1.4.4+)
bun outdated                   # Show outdated packages
bun info pkg                   # Show package metadata
bun info pkg versions          # List all available versions
bun info pkg version license   # Several properties at once, npm view paths too (v1.4.4+)
bun why pkg                    # Explain why a package is in the tree
bun pm ls                      # List installed packages (alias: bun list)
bun pm ls react                # Every installed copy of react (v1.4.4+)
bun pm ls --all                # List all (including transitive)
bun pm hash                    # Print lockfile hash
bun pm cache                   # Show cache directory
bun pm cache rm                # Clear cache (including the global virtual store)

1.4 での変更点： bun update は、package.json に記載されたものだけでなく、推移的な依存関係も再解決します。また、bun update <name> は、その名前に依存するものがない場合に終了コード 1 でエラーになります（以前はパッケージを追加していました）。

メンテナンス（v1.4 以降）

bun audit fix                  # Upgrade vulnerable packages to the lowest safe version
bun audit fix --dry-run        # Preview
bun audit fix --latest         # Also apply fixes your declared ranges exclude
bun audit --prod               # Skip packages only devDependencies need; --omit dev|optional|peer (v1.4.4+)
bun dedupe                     # Collapse duplicate versions in bun.lock, then install
bun dedupe --check             # CI gate: exit 1 if duplicates remain
bun prune                      # Drop node_modules entries no longer in bun.lock
bun prune --production         # Also drop devDependencies -- build with them, ship without
bun prune --check              # CI gate: exit 1 if anything is removable, delete nothing (v1.4.4+)
bun pm licenses --prod --json  # License inventory
bun pm diff [email protected] 19.0.0  # What changed between two versions of a package
bun pm cache prune --dry-run   # Cached packages older than 30 days; --max-age <days> (v1.4.4+)

bun pm diff は、変更されたファイル、新しいインストールスクリプト、child_process、fs、net、vm の新しいインポートなどの概要を最初に表示し、その後に差分を表示します。最小化されたファイルは展開され、書式のみの変更は省略されます。依存関係の更新をレビューする際に便利です。

bun prune --production は、Docker のビルドステージに適しています。

COPY package.json bun.lock ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun run build
RUN bun prune --production

CI キャッシュと Docker レイヤー（v1.4.4 以降）

bun pm fetch は、bun.lock で固定されているすべてのパッケージをキャッシュにダウンロードし、それ以外は何も行いません。node_modules の作成、スクリプトの実行、ロックファイルの書き込みは行わないため、ダウンロードレイヤーは package.json または bun.lock が変更された場合にのみ再構築されます。

COPY package.json bun.lock ./
RUN bun pm fetch
COPY . .
RUN bun install --offline --frozen-lockfile

モノレポでは、この 2 つのルートファイルで全ワークスペースをカバーできます。ただし、レイヤーにコピーする必要があるものもあります。bunfig.toml / .npmrc のレジストリ設定（キャッシュエントリはレジストリホストごとにキー付けされるため、これらがないとインストール時にすべて再ダウンロードされます）、ロックファイルに記載されたパッチファイルとローカル tarball、そしてルートの package.json が workspace: で依存しているワークスペースです。

レジストリトークンをイメージに含めないでください。 リテラルの _authToken を含む .npmrc をコピーすると、その内容がレイヤーとビルドキャッシュに残ります。.npmrc では ${NPM_TOKEN}（bunfig.toml では $NPM_TOKEN）としてトークンを記述し、その値をビルドシークレットとして渡します（BuildKit、Dockerfile syntax 1.10 以降）。

COPY package.json bun.lock .npmrc ./    # .npmrc: //npm.pkg.github.com/:_authToken=${NPM_TOKEN}
RUN --mount=type=secret,id=npm_token,env=NPM_TOKEN bun pm fetch

bun pm cache pack <file> は、ロックファイルで必要なキャッシュエントリを 1 つのファイルに書き込みます。bun pm cache unpack <file> は、別のランナーでそれらを復元し、不足しているものだけを追加します。

bun pm cache pack .ci/bun-cache.pack     # after an install
bun pm cache unpack .ci/bun-cache.pack   # next job, before bun install --frozen-lockfile

リンクとパッチ

bun link                       # Register current package as linkable
bun link pkg-name              # Link a registered package into node_modules; package.json is untouched
bun link --save pkg-name       # Also add "pkg-name": "link:pkg-name" to package.json
bun pm pack                    # Create tarball of package
bun patch pkg                  # Start patching a package
bun patch --commit pkg-dir     # Apply patch

v1.4.4 以降、link: はパスを指定します（"tokens": "link:./vendor/tokens"）。パスは、それを宣言する package.json からの相対パスです。Bun はディレクトリをシンボリックリンクするため、事前に bun link を実行する必要はありません。ディレクトリ自体の依存関係はインストールされません。その場合は file: またはワークスペースを使用してください。また、公開するパッケージではこれを宣言しないでください。パスのない link:name は、引き続き bun link で登録されたパッケージを意味します。Bun 1.4.3 では、このようなパスを指定すると failed to resolve というエラーが発生していました。

公開

bun publish                    # Publish to npm
bun publish --dry-run          # Preview what would be published
bun publish --tag beta         # Publish with tag
bun publish --access public    # Set access level
bun publish --recursive        # Every workspace not on the registry yet, dependencies first (v1.4.4+)
bun publish --filter '@acme/*' # Only the matching workspaces (v1.4.4+)

--recursive は、最初のパッケージを公開する前にすべてのパッケージをパックし、プライベートパッケージはスキップします。リリースノートによると、レジストリにすでに存在するバージョンもスキップするため、失敗後に再実行しても安全です。1.4.4 での変更点： 2.0.0-beta.1 のようなプレリリースバージョンには、--tag または publishConfig.tag が必要です。npm 11 のように latest タグを付けるのではなく、bun publish は prerelease needs a tag で終了します。また、publishConfig.registry で公開先を設定できます（リリースノートを参照）。

未宣言の依存関係：packageExtensions（v1.4.4 以降）

インポートするものを宣言していないパッケージは、分離リンカーのもとで失敗します。パッチを適用したりフォークしたりする代わりに、ルートの package.json から不足しているエントリを追加します。これは pnpm/Yarn 形式であり、Bun はそれらのロックファイルを移行するときにこの形式を引き継ぎます。

{
  "packageExtensions": {
    "legacy-plugin@2": { "dependencies": { "lodash": "^4.17.21" } },
    "react-redux@7": { "peerDependencies": { "react": "*" } }
  }
}

参考： フラグの詳細については、references/package-management.md を参照してください。

インストールレイアウト：リンカーとグローバル仮想ストア

node_modules のレイアウトを決める設定は 2 つあります。どちらも見た目以上に重要です。

リンカー

	hoisted	isolated
レイアウト	npm スタイルのフラットな node_modules	node_modules/.bun/ へのシンボリックリンク（pnpm スタイル）
ファントム依存関係	暗黙に解決されます	本来あるべきように失敗します
デフォルトになる条件	configVersion = 0（すべてのプロジェクト）、またはワークスペースのない configVersion = 1	configVersion = 1 かつ プロジェクトがワークスペースを使用している

デフォルトは Bun のバージョンではなく、ロックファイルの configVersion によって決まります。configVersion = 1 かつ プロジェクトがワークスペースを使用している場合に限り、isolated になります。v1.3.2 より前に作成されたロックファイルは configVersion = 0 として扱われ、hoisted のままなので、Bun をアップグレードしても既存プロジェクトのレイアウトは変わりません。--linker または [install] linker で上書きできます。

グローバル仮想ストア（v1.3.14 以降、1.4 で高速化）

パッケージファイルは ~/.bun/install/cache/links/ に一度だけ保存され、各プロジェクトはそこにシンボリックリンクを作成します。ウォームインストールはおよそ 7 倍高速になり、node_modules は数百 MB から数 MB のリンクに縮小されます。デフォルトでは無効で、両方の設定が必要です。linker = "hoisted" の場合、globalStore フラグは無視されます。

[install]
linker = "isolated"      # prerequisite
globalStore = true

BUN_INSTALL_GLOBAL_STORE=1 bun install --linker isolated   # per invocation
bun pm cache rm                                            # clears the store too

有効にする前に知っておくべき影響は次のとおりです。

1. node_modules のほとんどはシンボリックリンクです。 find node_modules -name '*.mdx' と rg <pattern> node_modules は何も返さず、du -sh node_modules はリンク先ではなくシンボリックリンクを測定するため、約 0B と表示されます（実際のツリーは数 MB のリンクです。du -sh -L ではリンク先のサイズが表示され、リンクごとに 1 回ずつカウントされます）。ファイルには明示的なパスでアクセスするか、find -L を渡してください（リンク層をたどるため、二重にカウントされます）。 node_modules をシンボリックリンクをたどらずにスキャンするツールの動作は異なります。pnpm スタイルのレイアウトと同様の注意点です。
2. すべてのプロジェクトで同じ inode が共有されます。 node_modules/ 内のファイルを編集すると、マシン上のすべてのプロジェクトに反映されます。bun patch を使用してください。
3. 実際のファントム依存関係は解決されなくなります。 パッケージはキャッシュ内の実パスを使用するため、隠れた node_modules/.bun/node_modules/ 層はパッケージ内部からの解決経路に含まれなくなります。依存関係を宣言するか、globalStore = false を設定してください。
4. 一部のエントリはプロジェクト内に残ります。パッチ適用済みのパッケージ、trustedDependencies、および workspace:、file:、または link: 依存関係に依存するものが該当します。対象外であることは依存関係グラフの上位にも伝播するため、いずれにせよモノレポではツリーのかなりの部分がローカルに残ります。

参照：node_modules/bun-types/docs/pm/global-store.mdx および pm/isolated-installs.mdx。

自己完結型ワークスペース（v1.4.1 以降、hoisted リンカー）

Electron のパッケージャーやサーバーレスのバンドラーは、あるワークスペースの node_modules を再パッケージ化し、すべての依存関係がその配下に物理的に存在することを前提とします。そのようなワークスペースをルートの package.json に記載するか、ワークスペース自身のファイルで Yarn の "installConfig": { "hoistingLimits": "workspaces" } を設定してください。

{ "workspaces": { "packages": ["apps/*", "packages/*"], "selfContained": ["apps/desktop"] } }

そのワークスペースが直接または間接的に依存するものは、apps/desktop/node_modules より上位に hoist されず、これらのパッケージはキャッシュへのハードリンクではなく実際のコピーになります。ロックファイルには記録されず、isolated リンカーでは効果がありません。

スクリプトとファイルの実行

直接実行

bun file.ts                    # Run TypeScript/JavaScript directly
bun run script-name            # Run package.json script
bun script-name                # Short form (if no conflict with bun commands)
bun --watch file.ts            # Re-run on file changes
bun --hot file.ts              # Hot reload (preserves state)
bun --env-file .env file.ts    # Load env file
bun --env-file .env.local --env-file .env file.ts  # Multiple env files
bun --no-env-file file.ts      # Skip automatic .env loading (CI/prod; `env = false` in bunfig)
bun --env-file=<(op inject -i .env.tpl) file.ts   # 1Password CLI renders dotenv lines; any pipe/FIFO//dev/stdin works (v1.4.1+)
bun --no-ffi-cc file.ts        # cc() from bun:ffi throws ERR_FFI_CC_DISABLED (v1.4.1+)
bun --check file.ts            # Type check the file and its imports first; nothing runs on an error (v1.4.3+)
bun --disallow-code-generation-from-strings=strict server.ts   # eval/new Function/node:vm/data: imports throw EvalError (v1.4.3+)
bun --no-orphans run dev       # Die with the parent, SIGKILL every descendant on exit
bun repl                       # Native REPL: highlighting, history, completion (v1.3.10+)
bun repl -p '{ a: 1 }'         # Evaluate and print with REPL semantics
bun exec 'ls | wc -l'          # Run a shell script through Bun's shell
bun ./README.md                # Render Markdown in the terminal, no VM started

bunx（npx の代替）

bunx command                   # Run package binary (auto-installs if needed)
bunx --bun command             # Force Bun runtime for the command
bunx command@version           # Run specific version
bunx --cwd packages/api --env-file ci.env prisma migrate deploy   # Another directory, an env file (v1.4.4+)

v1.4.4 以降、bunx は自身の未知のフラグに対して終了コード 1 を返します（bunx has no --x flag. Flags for the package go after its name.）。1.4.3 ではそのフラグを無視して、ツールを実行していました。

並列実行と逐次実行

npm-run-all と concurrently の代替です。出力にはスクリプトごとのプレフィックス（--filter 使用時は package:script）が付き、pre*／post* フックはメインのスクリプトとまとめて実行されます。

bun run --parallel build lint typecheck        # Run all concurrently
bun run --parallel 'build:*'                   # Glob-match script names
bun run --parallel --filter '*' build          # Fan out across every workspace
bun run --parallel --no-exit-on-error --filter '*' test   # Keep going past failures
bun run --sequential clean build deploy        # One at a time, same prefixed output

このフラグは run より前に指定することもできます（bun --parallel run build lint）。どちらの形式も使用できます。

ワークスペース対応の実行

bun --filter 'pkg-name' run script    # Run in specific workspace
bun --filter '*' run script           # Run in all workspaces
bun --filter './apps/*' run build     # Run with glob pattern

スクリプトフラグ

bun run --smol file.ts         # Reduce memory usage (sacrifice throughput)
bun run --silent script        # Suppress script name echo
bun run --shell=bun script     # Use Bun's built-in shell (cross-platform, default on Windows)
bun run --shell=system script  # Use system shell (default on macOS/Linux)

ゼロ設定のフロントエンド開発

HTML ファイルを開発サーバーとして直接実行できます。Vite、Webpack、設定ファイルは不要です：

bun ./index.html               # Start dev server, auto-bundles JS/TS/CSS
bun --hot ./index.html         # With hot module replacement

Bun は、TypeScript、JSX、TSX、および HTML からリンクされた CSS を自動的にトランスパイルします。<script> タグ内の node_modules インポートを解決します。HMR と React Fast Refresh を有効にします。

v1.4.4 以降では、--port 3000 と --host 0.0.0.0 はスペース区切りで指定できます。Bun 1.4.3 では --port=3000 のように記述しないと無視され、指定にかかわらずポート 3000 で配信されていました。

参考：詳しくは references/running-and-execution.md を参照してください。

型チェック（v1.4.3 以降）

bun check は組み込みの TypeScript 7 移植版です。tsconfig.json を読み込み、tsc と同じ診断を出力します。すべての CPU コアを使用し、typescript パッケージは不要で、ファイルへの書き込みも行いません。エラーがある場合は終了コード 1、問題がない場合は 0、チェック対象がない場合は 1 で終了します。

bun check                          # the project of the nearest tsconfig.json
bun check src/index.ts             # one file and everything it imports
bun check -b                       # every project in `references`, like tsc -b -- nothing pre-built
bun check --no-script              # the type checker even when package.json has a "check" script (v1.4.4+)
bun --check src/index.ts           # type check, then run; nothing runs on an error
bun test --check                   # no test runs on an error
bun build --check ./app.ts --outdir dist   # nothing is written on an error
bun --watch --check src/index.ts   # re-check before every restart (there is no bun check --watch)

• types を bun-types に設定してください。 Bun の型定義がない場合や、古い @types/bun を使っている場合は、Bun、bun:test、およびインストール済みの型定義より新しいすべての API のチェックに失敗します。上記の「バージョンを確認する」を参照してください。
• check スクリプトが優先されます。 package.json に check が定義されている場合、bun check はシェルからでも他のスクリプトからでもそのスクリプトを実行します。そのため、bun init が作成する "typecheck": "bun check" は lint スクリプトを実行し、指定したフラグもそのスクリプトに渡されます。型チェッカーとして bun check が動作するのは、check スクリプト内と、そこから起動されるスクリプト内だけです。bun --check と bun check --no-script（v1.4.4 以降）は常に型チェックを行うため、スクリプトや CI ではどちらかを使用してください。1.4.3 では --no-script はフラグではなく、check スクリプトが実行されてそれを受け取るため、Bun のバージョンが異なる環境では bun --check を使ってください。古い Bun では、"check": "bun check" は無限に自分自身を呼び出します。
• エージェント向けの出力。 CLAUDECODE=1、AGENT=1、または REPL_ID=1 が設定されていると、エラーはソース行を含む <error file= line= column= code=> ブロックとして出力されます。--no-pretty を指定すると、エラーごとに file(line,col): error TSxxxx: ... の形式で 1 行ずつ出力されます。パイプに出力すると、これがデフォルトになります。サマリーは stderr に出力されます。
• インストール済みの typescript のバージョンにかかわらず、TypeScript 7 のルールが適用されます。 strict は有効で、types は明示的に列挙しない限り空です。削除済みのオプション（baseUrl、moduleResolution: "node"、target: "es5"）があると、ファイルのチェック前に処理が停止します。
• .d.ts の出力には tsc を使ってください。 bun check は何も出力しません。

参考：--check の対象範囲、出力形式、モノレポ、CI、および TypeScript 5 から 7 への移行表については、references/type-checking.md を参照してください。

フォーマット（v1.4.4 以降）

bun fmt は Bun に組み込まれた Prettier 互換フォーマッターです。JavaScript、TypeScript、CSS、HTML、JSON、YAML、Markdown などに対応し、Prettier または oxfmt の設定をそのまま読み込みます。prettier パッケージは不要です。1.4.3 以前では Script not found "fmt" というエラーで失敗します。

bun fmt                            # format in place
bun fmt --check                    # write nothing; exit 1 if a file needs formatting, 2 on an error
bun fmt --staged                   # pre-commit: format staged files and stage them again
bun fmt --changed                  # files that differ from the default branch (--changed=<ref>)
bun fmt --init                     # add a [fmt] section to bunfig.toml

• check と同様に、fmt スクリプトが優先されます。 bun fmt --check は、シェルからでも他のスクリプトからでも、末尾に --check を追加して fmt スクリプトを実行します。スクリプト、フック、CI では bun fmt --no-script を記述してください。
• 指定順にかかわらず、--write は --check より優先されます。 bun fmt --check --write はフォーマットを実行し、終了コード 0 で終了します。
• 設定は bunfig.toml の [fmt]（すべての Prettier オプションを camelCase 名で指定します。不明なキーがあると終了コード 2 で終了します）、または既存の .prettierrc／.oxfmtrc.json で行います。sortImports、sortTailwindcss、sortPackageJson、jsdoc はオプトインで、有効にすると対応する Prettier プラグインの代わりになります。
• bun format はエイリアスではありません。format スクリプトを実行します。

参考：終了コード、設定の優先順位、プラグイン、無視ルール、一部のファイルだけがステージされた場合の --staged、および CI については、references/formatting.md を参照してください。

テスト

Bun には、Jest に似た構文と互換性のある組み込みテストランナーが含まれています。

テストの実行

bun test                          # Run all test files
bun test file.test.ts             # Run specific file
bun test foo bar                  # Positional args filter by FILE path, not test name
bun test -t "pattern"             # Filter by TEST NAME (regex); --grep is an alias
bun test --timeout 10000         # Set timeout (ms)
bun test --bail                   # Stop on first failure
bun test --bail 5                 # Stop after 5 failures
bun test --rerun-each 3           # Run each test 3 times
bun test --retry 3                # Default retry count for flaky tests
bun test --only                   # Run only tests marked with .only
bun test --todo                   # Include .todo tests
bun test --only-failures          # Print failures and the summary only
bun test --pass-with-no-tests     # Exit 0 when nothing matches (monorepos)
bun test --check                  # Type check test files + imports first; no test runs on an error (v1.4.3+)

--filter はテスト名のフィルターではありません。 bun test では、--filter は位置引数と同じファイルパス用のフィルターであり、-F は拒否されます。（ワークスペースの選択はパッケージマネージャーの機能です：bun run --filter '*' test。）テスト名を渡すと、通常は一致するファイルが見つからず、bun test はその後 1 で終了します（「一致するテストファイルがありません」）。つまり、この間違いによって実行は失敗し、何も通知されずに成功することはありませんが、それでもテストは実行されません。テスト名には -t ／ --test-name-pattern ／ --grep を使用してください。--pass-with-no-tests を指定すると、その終了コード 1 が 0 に変わり、この問題が隠れてしまいます。

カバレッジ

bun test --coverage               # Enable code coverage
bun test --coverage-reporter text # Coverage format: 'text' and/or 'lcov' -- there is no 'json'
bun test --coverage-dir ./cov     # Output directory

v1.4.3 以降、--coverage-reporter を指定すると --coverage も有効になります。それ以前は、--coverage-reporter=lcov だけではテストは実行されても、レポートは出力されませんでした。

1.4.4 で変更 — より厳密なカウント。 実行されなかったコードはカバレッジに含まれなくなります。具体的には、独立した行にある ||、&&、??、?: のうち通らなかった側、?. または ??= によってスキップされたコード、関数が再開しなかった場合の await 以降の行が該当します。コードを変更していなくても、アップグレードによって % Lines が低下することがあります。その場合は coverageThreshold の基準値を再設定してください。% Funcs では、暗黙的なコンストラクター、フィールド初期化子、static ブロックがカウントされなくなるため、上昇する場合があります。あるファイルでは、1.4.3 で行カバレッジ 100% ／関数カバレッジ 83% だったものが、1.4.4 では 67% ／ 100% になりました。

並列実行、シャーディング、分離

bun test --parallel               # Files across N worker processes (default: CPU count)
bun test --parallel=4 --isolate   # Explicit worker count
bun test --isolate                # Fresh globalThis per file, same process (Jest/Vitest default)
bun test --shard=1/3              # One CI runner's slice of the files
bun test --changed=main           # Only files your diff reaches (walks the import graph)
bun test --timings=t.json --update-timings   # Record per-file durations
bun test --parallel --shard=1/3 --timings=t.json   # Balance by wall time, not file count

• --parallel を指定すると --isolate も有効になります。--no-isolate を指定するとこれを無効にでき、各ワーカーは単一のグローバルとモジュールレジストリーを再利用します。
• --isolate は、ファイル間で globalThis とモジュールレジストリーをリセットし、ファイルが開いたままにしたサーバー、ソケット、ウォッチャー、サブプロセスを終了することで、「単独では成功するが、テストスイートでは失敗する」問題を解消します。トランスパイル済みのソースとバイトコードはグローバル間でキャッシュされるため、コストは低く抑えられます。
• ワーカーは、1 から始まるスロット番号を JEST_WORKER_ID ／ BUN_TEST_WORKER_ID として公開します。そのため、JEST_WORKER_ID を使ってデータベースやポートを割り当てる Jest のセットアップは、変更せずに動作します。
• カバレッジと JUnit の出力はワーカー間で統合されます。--bail を指定すると、すべてのワーカーが停止します。
• --timings（v1.4 以降）を使うと、シャードのサイズはファイル数ではなく 実行時間 が均等になるように調整されます。また、ファイルは実行時間の長い順に書き出されるため、遅いテストのレポートとしても使えます。
• 1.4.1 では、mock()、spyOn()、mock.module()、または Bun.plugin() を使用するファイルが --isolate の下で以前のモジュールグラフを保持しなくなり、大規模なテストスイートでもメモリー使用量が安定します。

テストファイルのパターン

デフォルトでは、Bun は次のパターンに一致するファイルを検出します：*.test.{ts,tsx,js,jsx}、*_test.{ts,tsx,js,jsx}、*.spec.{ts,tsx,js,jsx}、*_spec.{ts,tsx,js,jsx}、および __tests__/ ディレクトリー内のファイル。--path-ignore-patterns <glob> または bunfig.toml の test.pathIgnorePatterns を使ってパスを除外できます。

スナップショットテスト

bun test --update-snapshots       # Update snapshot files

ウォッチモード

bun test --watch                  # Re-run on file changes

リファレンス：テスト API、モック、ライフサイクルフック、カバレッジ設定については、references/testing.md を参照してください。

バンドルとコンパイル

バンドリング

bun build ./src/index.ts --outdir ./dist           # Bundle to directory
bun build ./src/index.ts --outfile ./dist/out.js    # Bundle to single file
bun build ./src/index.ts --target browser           # Target: browser (default), bun, node
bun build ./src/index.ts --format esm               # Format: esm (default), cjs, iife
bun build ./src/index.ts --minify                   # Minify output
bun build ./src/index.ts --sourcemap external        # Sourcemaps: external, inline, linked, none
bun build ./src/index.ts --splitting                # Code splitting (ESM only)
bun build ./src/index.ts --splitting --min-chunk-size=16384   # Fold tiny side-effect-free chunks into their loaders (v1.4.1+)
bun build ./src/index.ts --outdir ./dist --check    # Type check first; nothing is written on an error (v1.4.3+)

1.4.1 で変更 — 出力の分割。 エントリーと遅延読み込みされるルートで共有されるコードはエントリーのチャンクに残ります（ファイル数が減り、各ファイルも小さくなります）。ブラウザビルドでは、エントリーまたは import() が読み込むすべてのチャンクに <link rel="modulepreload"> が追加されます（無効にするには --no-module-preload を指定します）。--target bun は ES モジュールの require() を専用チャンクに分割します（インライン化するには --no-split-require を指定します）。また、export * as / const { x } = await import() では未使用のエクスポートがツリーシェイキングされます。zod と effect のバンドルサイズは 50～80% 縮小します。ビルド出力のスナップショットテストは変更されます。

1.4.3 で変更 — チャンク名。 大規模な --splitting ビルドで Multiple files share the same output path エラーが発生しなくなりました。8 文字の [hash] が衝突した異なる 2 つのチャンクには、名前が異なるまで文字が追加されます。[hash9] から [hash13] では最小文字数を拡張できます（[hash13] は 64 ビットハッシュ全体です。1.4.2 ではトークンがそのまま出力され、エラーになっていました）。共有コードが、名前に [hash] を含まないエントリチャンクに統合されなくなりました。そのため、クエリ文字列付きで読み込まれるエントリー（index.js?v=1）が 2 回実行されることはありません。これは 1.4.1 で発生したリグレッションでした。metafile.inputs 内の分割された各 import() では、読み込むファイルが entryPoint に記載されます。

スタンドアロン実行可能ファイル

bun build ./src/cli.ts --compile                    # Create self-contained executable
bun build ./src/cli.ts --compile --target bun-linux-x64    # Cross-compile
bun build ./src/cli.ts --compile --minify           # Minified executable

利用可能なコンパイルターゲット：bun-linux-x64、bun-linux-arm64、bun-darwin-x64、bun-darwin-arm64、bun-windows-x64。

ブラウザーターゲット（v1.3.10 以降）— 自己完結型の HTML ファイルにコンパイルします：

bun build --compile --target=browser ./app.tsx --outfile ./dist/app.html

ビルドオプション

bun build ... --external pkg        # Exclude from bundle
bun build ... --define 'KEY=VALUE'  # Define compile-time constants
bun build ... --loader .ext=type    # Custom loaders (js, jsx, ts, tsx, json, css, text, file, base64, dataurl, binary)
bun build ... --entry-naming [dir]/[name].[ext]   # Output naming pattern
bun build ... --chunk-naming 'chunk-[hash13].[ext]'   # Wider minimum hash: [hash9]..[hash13] (v1.4.3+)
bun build ... --public-path /cdn/   # Public path prefix for assets
bun build ... --react-compiler      # React auto-memoization, no Babel/SWC (v1.4+)
bun build ... --metafile meta.json  # esbuild-format build metadata
bun build ... --metafile-md meta.md # Module graph as Markdown, for reading or an LLM (v1.3.8+)
bun build ... --feature=FLAG        # Compile-time flag for `feature()` from bun:bundle
bun build ./src/cli.ts --compile --asset ./public --asset ./templates   # Embed files/dirs (v1.4+)
bun build ./src/cli.ts --compile --bytecode --bytecode-depth=1   # Bytecode for top-level + one nesting level (v1.4.1+)
bun build ... --no-deprecated-namespace-object-setters   # Getter-only `import * as ns` objects, the future default (v1.4.1+)

--asset（v1.4 以降）は、元のファイル名を保ったままファイルまたはディレクトリを --compile 実行可能ファイルに埋め込みます。そのため、path.join(import.meta.dir, ...) はディスク上と同じように解決されます。node:fs は /$bunfs/ を実際のツリーとして扱うため、バイナリ内で readdirSync（recursive / withFileTypes を含む）が動作します。起動時にディレクトリを列挙する静的ファイルサーバーは、変更なしで実行できます。

v1.3.4 で変更： --compile バイナリは実行時の作業ディレクトリから tsconfig.json または package.json を自動読み込みしなくなりました（--compile-autoload-tsconfig / --compile-autoload-package-json で再び有効にできます）。.env と bunfig.toml は引き続き自動読み込みされます。 --bytecode は v1.3.9 で ES モジュールのサポートが復活しました（--format=esm、--compile が必要）。これにより、トップレベル await、import.meta、動的インポート、コード分割が可能になります。それまでは CommonJS が強制されていました。 v1.4.1 では、バイトコードのサイズはソースの約 9 倍から約 3 倍になりました。--bytecode-depth=N は事前コンパイルを N 段階のネストまでに制限します（それより深い関数は初回呼び出し時にコンパイルされます）。また、--bytecode を使ったクロスコンパイルがすべてのターゲットで動作し、macOS または Linux からの bun-windows-x64 も含め、出力はバイト単位で同一になります。

プロファイルに基づくバイトコード配置（v1.4.3 以降）。 --bytecode-order を指定すると、記録した実行で使用されたバイトコードを --compile --bytecode 実行可能ファイルの先頭に配置するため、実行可能ファイル自身の読み取りとデコードが少なくなります（大規模な CLI の例では、コールドスタートが 1.01 秒から 0.53 秒に短縮されます）。--compile --bytecode が必要です。

bun build ./src/cli.ts --compile --bytecode --outfile mycli                               # 1. build
BUN_BYTECODE_ORDER_OUT=mycli.order ./mycli --help                                         # 2. run it as users do; written on exit
bun build ./src/cli.ts --compile --bytecode --bytecode-order=mycli.order --outfile mycli  # 3. rebuild with the profile

関数は構文のハッシュで照合されるため、先週のプロファイルも引き続き適用できます。コミットするか、キャッシュしてください。--bytecode-order=a.order,b.order では複数のプロファイルを指定でき、使用頻度の高いものを先に配置します。bun:jsc の bytecodeOrderStats() は、プロファイルが実行のどの程度をカバーしたかを報告します。 --compile-jit-policy <n> は、JIT の段階的最適化のしきい値を n 倍にして実行可能ファイルを起動するため、一度だけ実行される起動コードはインタープリターで実行されます。アプリが操作可能になったら、Bun.unsafe.setJITPolicy(1) を呼び出してください。--no-optimize-bytecode はビルド時のバイトコード最適化をスキップします。

リファレンス：オプションの詳細については、references/bundling-and-compilation.md を参照してください。

プロジェクトの初期化

bun init                       # Initialize new project (creates package.json, tsconfig.json, index.ts)
bun init -y                    # Accept defaults, no template picker
bun init --react               # React template (also --react=tailwind, --react=shadcn)
bun init --minimal             # Type definitions only
bun create template-name       # Create from template
bun create next-app my-app     # Example: create Next.js app

bun init は、Bun 独自のエージェントルールを記した CLAUDE.md もプロジェクトのルートに書き込みます （node_modules/bun-types/CLAUDE.md からコピーされます）。「node／npm ではなく bun を使う」こと、API の置き換え一覧、HTML インポートを使うフロントエンドのパターンが記載されています。新しい Bun プロジェクトでは実行することをおすすめします。リポジトリで作業するすべてのエージェントに共通の基準を適用し、同梱ドキュメントへの参照も示せます。

1.4.3 での変更点： bun init は "typecheck": "bun check" スクリプトを追加します（プロジェクトに check スクリプトがある場合は bun --check にしてください）。また、コピーされるルールでは tsc --noEmit の代わりに bun check を使うようになりました。引き続き "@types/bun": "latest" と "types": ["bun"] が追加されますが、各 Bun リリース後、1 日以上前のバージョンが解決される場合があります。bun-types に置き換えてください（「バージョンの確認」を参照）。

1.4 での変更点： bun init は typescript: ^7 を書き込むようになりました（以前は ^5、または React テンプレートでは何も書き込まれませんでした）。また、stdin が非 TTY の場合（CI、パイプ経由の spawn）、テンプレート選択画面を開かずに bun init -y と同じ動作をします。非 TTY の stdin で bun update -i を実行すると、終了コード 1 で終了するようになりました。代わりに bun update または bun outdated を使ってください。

設定（bunfig.toml）

主なセクション：

[run]
bun = true                     # Always use Bun runtime (not Node)

[install]
exact = true                   # Pin exact versions by default
peer = false                   # Don't auto-install peer deps
production = false             # Include devDeps
frozenLockfile = false         # Don't fail on lockfile mismatch
globalDir = "~/.bun/install/global"  # Global install location
linker = "isolated"            # "isolated" or "hoisted" -- see gotchas
globalStore = true             # Share package files across projects (requires isolated)
offline = false                # true: never touch the network, every package must be cached (v1.4.1+)
prefer = "online"              # "offline": cached metadata regardless of age (v1.4.1+); "latest": always check
minimumReleaseAge = "3d"       # Supply-chain delay; units are v1.4.4+ ("90m", "12 hours"), a number is seconds
minimumReleaseAgeExcludes = ["@types/bun", "[email protected]"]   # name: every version; name@version: that release (v1.4.4+)

[install.scopes]
"@myorg" = { token = "$NPM_TOKEN", url = "https://npm.pkg.github.com/" }

[fmt]                          # bun fmt (v1.4.4+): every Prettier option by its camelCase name
printWidth = 100
sortImports = true

[test]
coverage = false               # Enable coverage by default
coverageReporter = ["text", "lcov"]
timeout = 5000                 # Default test timeout
pathIgnorePatterns = ["**/e2e/**"]   # Exclude test files by glob

[bundle]
entryPoints = ["./src/index.ts"]
outdir = "./dist"

リファレンス：bunfig.toml の完全なリファレンスについては、references/configuration.md を参照してください。

デバッグとプロファイリング

bun --inspect file.ts              # Start debugger (WebSocket, connect via Chrome DevTools)
bun --inspect-wait file.ts         # Wait for debugger to attach before executing
bun --inspect-brk file.ts         # Break on first line
bun --cpu-prof file.ts             # Generate CPU profile
bun --cpu-prof-md file.ts          # CPU profile as Markdown (v1.3.7+)
bun --heap-prof file.ts            # Generate heap profile
bun --heap-prof-md file.ts         # Heap profile as Markdown (v1.3.7+)
BUN_JSC_logJITCodeForPerf=1 bun file.ts  # Linux perf integration

環境変数

bun --env-file .env file.ts        # Load .env file
bun --env-file .env.local --env-file .env file.ts  # Load multiple (left takes precedence)

Bun はデフォルトで、NODE_ENV に基づいて .env、.env.production、.env.local、.env.production.local を自動的に読み込みます。

外部ツールを置き換える組み込み機能

Bun には、外部パッケージやツールを不要にする多くの機能が組み込まれています。

ネイティブ TypeScript

Bun は .ts、.tsx ファイルを直接実行します。tsc、ts-node、tsx は不要です。トランスパイラーはランタイムに組み込まれています。bun file.ts を使えば、任意の TypeScript ファイルをすぐに実行できます。

組み込みの型チェッカー

bun check（v1.4.3 以降）は tsc --noEmit に代わるもので、--check を指定すると、型チェックが問題なく完了した場合にのみ bun <file>、bun test、bun build を実行します。typescript パッケージは不要です。.d.ts ファイルの出力にのみ tsc を使ってください。

組み込みのフォーマッター

bun fmt（v1.4.4 以降）は、フォーマットにおいて prettier、oxfmt、lint-staged に代わるもので、Prettier のインポート並べ替え、Tailwind、package.json、Svelte の各プラグインにも対応します。既存の Prettier または oxfmt の設定を読み込みます。

ワークスペースカタログ

Bun は package.json の catalog: プロトコルに対応しており、モノレポのワークスペース全体で依存関係のバージョンを一元管理できます。syncpack や manypkg のようなツールは不要です。

// Root package.json
{
  "workspaces": ["packages/*"],
  "catalog": {
    "react": "^19.0.0",
    "typescript": "^5.7.0"
  }
}

// packages/app/package.json
{
  "dependencies": {
    "react": "catalog:"
  }
}

組み込みのテストランナー

bun test は、スナップショットテスト、モック、カバレッジに対応した Jest 互換のフル機能テストランナーです。jest、vitest、mocha は不要です。

組み込みのバンドラー

多くの用途で bun build は esbuild、webpack、rollup に代わります。コード分割、ツリーシェイキング、ミニファイ、スタンドアロン実行ファイルのコンパイルに対応しています。

組み込みの SQLite

import { Database } from 'bun:sqlite' — プリペアドステートメントとトランザクションに対応した、依存関係不要の SQLite3 です。better-sqlite3 や sql.js は不要です。

組み込みのシェル

Bun.$ タグ付きテンプレート — エスケープを自動的に行う、クロスプラットフォームのシェル実行機能です。execa、shelljs、zx に代わります。

組み込みのファイル I/O

Bun.file() と Bun.write() — fs をインポートせずに高速なファイル操作ができます。MIME タイプを自動検出します。

組み込みの Glob

new Bun.Glob(pattern) — 高速な Glob マッチングとファイルスキャンができます。glob、fast-glob、minimatch に代わります。

組み込みのパスワードハッシュ化

bcrypt と argon2id に対応した Bun.password.hash() と .verify() を使えます。bcrypt、argon2 パッケージに代わります。

組み込みの圧縮

Bun.gzipSync()、Bun.deflateSync()、Bun.zstdCompressSync() — zlib のラッパーパッケージは不要です。

組み込みの Semver

Bun.semver.satisfies()、.order() — semver パッケージに代わります。

組み込みのランタイム API

Bun に組み込まれたランタイムヘルパー（Bun.s3、Bun.redis、Bun.Archive、JSONC、JSON5、JSONL、markdown、cron）については、bun-api スキルを参照してください。

ゼロ設定のフロントエンド開発サーバー

bun ./index.html — JS／TS／CSS を自動バンドルし、HMR と React Fast Refresh に対応した HTML サーバーを起動します。シンプルなプロジェクトでは Vite／Webpack の開発サーバーの代わりになります。

ES デコレーター

TC39 標準の ES デコレーターをネイティブでサポートしています（v1.3.10+）。experimentalDecorators の tsconfig 設定は不要です。

主な注意点

1. Bun プロジェクトでは、必ず npm／node／npx ではなく bun を使ってください
2. ロックファイルの形式：新規プロジェクトでは、テキスト形式の bun.lock（v1.2 以降）がデフォルトです。旧形式の bun.lockb はバイナリです。package-lock.json と混在させないでください。v1.4 以降では lockfileVersion: 2 が書き込まれます（ネストされたオーバーライドやバージョン指定のオーバーライドを使う場合は 3）。Bun 1.3 はバージョン 3 を読み込めません。古い Bun を固定している CI のリポジトリにコミットする前に確認してください。
3. trustedDependencies：ライフサイクルスクリプト（postinstall など）は、package.json の trustedDependencies に記載されたパッケージに対してのみ実行されます。v1.3.5 以降では、デフォルトの信頼対象リストは npm レジストリのパッケージにのみ適用されるため、file:／link:／git:／github: の依存パッケージが esbuild という名前でも、実際の esbuild のエントリーによる信頼は得られません。自分で一覧に追加してください。v1.4 以降では、エントリーは切り詰められたハッシュではなく、パッケージ名と完全一致します。
4. --bun フラグ：Next.js など、一部のツールは bun run で実行してもデフォルトで Node.js を使います。Bun ランタイムを強制するには、--bun または bunfig.toml の [run] bun = true を使ってください。
5. ワークスペースプロトコル：ワークスペースパッケージを参照するには、package.json で "workspace:*" を使ってください。
6. グローバルバイナリ：bun add -g でインストールされ、~/.bun/bin/ に配置されます。
7. Node.js 互換性：Bun は Node.js API の大部分を実装していますが、一部の例外的なケースでは動作が異なります。互換性については https://bun.sh/docs/runtime/nodejs-apis を確認してください。
8. TypeScript：Bun はコンパイル手順なしで TypeScript をネイティブに実行します。独自のトランスパイラーを使うため（tsc ではありません）、実行時に型チェックは行われません。bun check または --check（v1.4.3 以降）を使ってください。
9. 自動インストール：Bun はインポート時に不足しているパッケージを自動インストールできます（デフォルトでは無効です。有効にするには、bunfig.toml で [install] auto = true を設定します）。
10. bun run と bun の違い：bun run script は package.json のスクリプトを実行し、bun file.ts はファイルを直接実行します。bun script はまずスクリプトを試し、次にファイルを実行します。
11. --filter はテスト名のフィルターではありません。 bun test では位置引数と同じくファイルパスを絞り込みます（-F は拒否されます。ワークスペースの選択には bun run --filter '*' test を使います）。bun test -t <regex>（または --grep）でテスト名を絞り込めます。指定を間違えると何も一致せず、終了コード 1 で終了します。ただし、--pass-with-no-tests が設定されている場合は、テストを実行していないのに成功扱いになります。
12. カバレッジレポーターは text と lcov のみです。--coverage-reporter=json は拒否されます。v1.4.3 以降、このフラグを指定すると --coverage も有効になります。
13. v1.4 以降、bunfig.toml は厳密な TOML として扱われます。 引用符で囲まれていない値、キーと値の組の間の改行の欠落、Number.MAX_SAFE_INTEGER を超える整数があると、起動時に SyntaxError が発生します。linker = isolated は linker = "isolated" とする必要があります。
14. node として起動した Bun は、.env を読み込まなくなりました（v1.4 以降）。 bun --bun、bunx --bun、または node のシンボリックリンク経由では、node を呼び出すスクリプトからこれらの変数が undefined として見えます。Node と同じ動作にするには、--env-file を渡してください。
15. 既存のプロジェクトでは、分離型リンカーはデフォルトで有効になりません。リンカーは Bun のバージョンではなく、ロックファイルの configVersion によって選択されます。上記の「インストールレイアウト」を参照してください。
16. x64 ビルドはベースライン専用です（v1.4 以降）。 -march=haswell ビルドはなくなりました。-baseline のダウンロード URL と npm パッケージは引き続き存在し、同じバイナリを含みます。また、CPU lacks AVX support の警告は削除されました。
17. bun feedback は 1.4 で削除されました。
18. バンドルされた名前空間オブジェクトは、今後ゲッターのみになります。 現在、bun build の import * as ns／export * as ns では ns.x = 1 が黙って受け入れられますが、--no-deprecated-namespace-object-setters（または deprecatedNamespaceObjectSetters: false）を指定すると、将来のデフォルトの動作を今すぐ有効にできます（v1.4.1 以降）。
19. 1.4.1 より前は、bun run --filter、--workspaces、--parallel、--sequential が自動検出された bunfig.toml を無視していました（--config を渡した場合を除く）。また、[define] または --drop の変更後、bun run は 4 KiB 以上のファイルに古いトランスパイルキャッシュを再利用していました。
20. Bun 1.4.1 の bun build は、同じブロック内でネストされた var の名前を let に変更することがありました。そのため、Elysia をインポートするバンドルは SyntaxError: Cannot declare a var variable that shadows a let/const/class variable で読み込みに失敗し、また let がパラメーターや catch のバインディングと同じ名前になって誤った値を計算することがありました。1.4.2 で修正済みです。出力を修正するのではなくアップグレードし、バンドルに 1.4.1 を固定しないでください。
21. check スクリプトは bun check を上書きします（v1.4.3 以降）。 package.json で check が定義されている場合、bun check はそれを実行します。他のスクリプトから呼び出した場合も同様ですが、check スクリプト自体が起動した場合は除きます。そのため、bun init の "typecheck": "bun check" は lint スクリプトを実行します。bun --check は常に型チェックを行い、v1.4.4 以降では bun check --no-script も同様です。スクリプトではどちらかを使ってください。古い Bun で "check": "bun check" を使うと、無限に自分自身を呼び出します。
22. @types/bun は Bun のリリースより遅れて更新されます。1 日以上遅れることも多く、そのため最新 API が bun check で拒否されることがあります（TS2339、TS2353）。代わりに bun-types@<runtime-version> を依存関係に追加し、"types": ["bun-types"] を設定してください。@types/bun と並行して bun-types をインストールしても、型チェックの対象は変わりません。
23. v1.4.3 以降、インストールではスキップしたパッケージはキャッシュされません。 ロックファイルなしで --production または --omit を指定してインストールすると、除外されたグループの tarball はダウンロードされないため、後から行う完全な --offline インストール用のキャッシュを準備できません。同じプラットフォームで、同じパッケージをインストールする操作を行ってキャッシュを準備してください。
24. --disallow-code-generation-from-strings は 1.4.3 以降、強制されます。それ以前の Bun はこのフラグを受け入れたものの、無視していました。eval() と new Function() は、Worker を含めプロセス全体で EvalError をスローするようになりました。=strict は node:vm、data:／blob: のインポート、ソーステキストを返すプラグインもブロックし、--inspect も拒否します。v1.4.4 の =strict では、プログラムに同梱されたコードのみ実行されます。--compile の実行ファイルは、ディスク上の JavaScript ファイル（直前に書き込んだファイルも含む）を拒否し、どのローダーであっても contents を返すプラグインは拒否されます。一方、JSON を保持する data: URL は許可されます（1.4.3 では拒否されていました）。
25. fmt スクリプトは bun fmt を上書きします（v1.4.4 以降）。別のスクリプトが bun fmt を呼び出した場合も、フラグはスクリプトに渡されます。スクリプト、フック、CI では bun fmt --no-script を記述してください。-w／--write は、指定順に関係なく --check を上書きします。
26. パッケージマネージャーのコマンドは、未知のフラグを拒否するようになりました（v1.4.4 以降）。npm／Yarn／pnpm のフラグは変換されます。Bun 1.4.3 では黙って無視されていたフラグを含む CI の行が、終了コード 1 になることがあります。また、1.4.3 では dependencies に保存されていた bun add --save-dev は、devDependencies に保存されるようになりました。
27. bun lint は canary 版のみです。 bun-types 1.4.4 では docs/lint/ に記載されていますが、安定版 1.4.4 ではプロジェクトの lint スクリプトが実行されます。
28. 1.4.4 ではカバレッジ数値が変わります。コードに変更がなくても、スキップされた分岐や、再開されなかった await の後の行がカバー済みとして数えられなくなるため、% Lines が coverageThreshold を下回ることがあります。
29. 1.4.4 より前は、bun install --dry-run がプロジェクトのライフサイクルスクリプトを実行していました。また、1.4.3 の bun check --no-script は --no-script を付けて check スクリプトを実行します。古い Bun では、どちらも読み取り専用の確認には安全ではありません。

参考資料

• references/migration-1.4.md -- CLI、パッケージマネージャー、バンドラー、テストランナーにおける 1.3 から 1.4.4 までの変更点
• references/package-management.md -- インストール／追加／更新／監査／pm フラグ、ワークスペース、リンカー、CI キャッシュ
• references/running-and-execution.md -- ランタイムフラグ、bunx、プロファイリング、監視／ホットリロード、コード生成のロックダウン
• references/type-checking.md -- bun check、--check、出力形式、TypeScript 7 のデフォルト、モノレポ、CI
• references/formatting.md -- bun fmt、終了コード、[fmt] 設定、Prettier／oxfmt の設定、git フック、CI
• references/testing.md -- テストランナー API、モック、カバレッジ、CI の調整
• references/bundling-and-compilation.md -- bun build、ターゲット、スタンドアロン実行ファイル
• references/configuration.md -- bunfig.toml の完全なリファレンス
• references/allowlist.md -- コピーして使える Bash(command:*) 権限パターン