Bun を使い始めると、npm や yarn との違いに戸惑うことはありませんか？特に、どのコマンドがどんな役割を持っているのか、オプションはどう使うのかを毎回調べるのは面倒ですよね。

この記事では、Bun の主要コマンドである bun install、bun run、bun x、bun test、bun build を中心に、実務で使える形で一括整理します。各コマンドの基本から応用、よく使うオプション、エラー対処まで網羅した早見表として活用いただけます。

Bun 主要コマンド早見表

以下の表は、Bun の主要 5 コマンドの役割と代表的なオプションをまとめたものです。

#	コマンド	主な役割	代表的なオプション	用途例
1	bun install	依存関係のインストール	--production, --frozen-lockfile, --no-save	プロジェクト初期化、CI/CD 環境構築
2	bun run	package.json のスクリプト実行	--bun, --watch, --env-file	開発サーバー起動、ビルド実行
3	bun x	npm パッケージの即時実行	-b, --version	CLI ツールの一時実行、バージョン確認
4	bun test	テストファイルの実行	--watch, --coverage, --timeout	ユニットテスト、E2E テスト
5	bun build	JavaScript/TypeScript のバンドル	--outdir, --target, --minify	本番用ファイル生成、最適化

各コマンド詳細早見表

bun install コマンド詳細

#	オプション	説明	使用例
1	（オプションなし）	package.json から全依存関係をインストール	bun install
2	<package>	特定パッケージを追加してインストール	bun install react
3	--production	devDependencies を除外してインストール	bun install --production
4	--frozen-lockfile	lockfile を更新せず厳密にインストール	bun install --frozen-lockfile
5	--no-save	package.json を更新せずインストール	bun install lodash --no-save
6	-d, --dev	devDependencies として追加	bun install -d typescript
7	-g, --global	グローバルにインストール	bun install -g prettier

bun run コマンド詳細

#	オプション	説明	使用例
1	<script>	package.json の scripts を実行	bun run dev
2	--bun	Node.js ではなく Bun ランタイムで強制実行	bun run --bun start
3	--watch	ファイル変更を監視して自動再実行	bun run --watch dev
4	--env-file	指定した環境変数ファイルを読み込む	bun run --env-file .env.local dev
5	--silent	スクリプトの出力を抑制	bun run --silent build

bun x コマンド詳細

#	オプション	説明	使用例
1	<package>	npm パッケージを即座に実行	bun x cowsay hello
2	-b, --bun	Bun ランタイムで実行	bun x -b tsx index.ts
3	<package>@<version>	特定バージョンを指定して実行	bun x create-react-app@latest my-app

bun test コマンド詳細

#	オプション	説明	使用例
1	（オプションなし）	すべてのテストファイルを実行	bun test
2	<file>	特定のテストファイルのみ実行	bun test src​/​utils.test.ts
3	--watch	ファイル変更を監視して自動再実行	bun test --watch
4	--coverage	カバレッジレポートを生成	bun test --coverage
5	--timeout <ms>	タイムアウト時間を指定（ミリ秒）	bun test --timeout 5000
6	--bail	最初の失敗でテストを中断	bun test --bail

bun build コマンド詳細

#	オプション	説明	使用例
1	<entry>	エントリーポイントを指定してバンドル	bun build .​/​src​/​index.ts
2	--outdir <dir>	出力先ディレクトリを指定	bun build .​/​src​/​index.ts --outdir .​/​dist
3	--outfile <file>	出力ファイル名を指定	bun build .​/​src​/​index.ts --outfile .​/​bundle.js
4	--target <target>	ターゲット環境を指定（browser/node/bun）	bun build .​/​src​/​index.ts --target browser
5	--minify	コードを圧縮	bun build .​/​src​/​index.ts --minify
6	--sourcemap	ソースマップを生成	bun build .​/​src​/​index.ts --sourcemap
7	--splitting	コード分割を有効化	bun build .​/​src​/​index.ts --splitting

背景

JavaScript ランタイムとパッケージマネージャーの進化

Node.js が登場して以来、JavaScript エコシステムは npm、yarn、pnpm と進化を続けてきました。しかし、依存関係のインストールやビルド処理には依然として時間がかかり、開発体験を損なう要因となっていました。

Bun は、こうした課題に対する解決策として 2022 年に登場した新しい JavaScript ランタイムです。Zig 言語で実装され、JavaScriptCore エンジンを採用することで、従来のツールを大幅に上回る速度を実現しています。

Bun の基本構成要素

Bun は単なるパッケージマネージャーではなく、以下の機能を統合したオールインワンツールです。

mermaidCopy codeflowchart TB
  bun["Bun<br/>統合ランタイム"]
  bun --> runtime["JavaScript/TypeScript<br/>ランタイム"]
  bun --> pkg["パッケージ<br/>マネージャー"]
  bun --> bundler["バンドラー"]
  bun --> test["テスト<br/>ランナー"]

  runtime --> exec["即時実行"]
  pkg --> install["高速インストール"]
  bundler --> build["最適化ビルド"]
  test --> coverage["カバレッジ測定"]

この図が示すように、Bun は複数のツールを 1 つに統合することで、ツールチェーンの管理コストを削減し、開発者体験を向上させています。

従来であれば、以下のような複数ツールを組み合わせる必要がありました。

#	機能	従来の構成	Bun での構成
1	ランタイム	Node.js + ts-node	bun run
2	パッケージ管理	npm / yarn / pnpm	bun install
3	バンドル	webpack / Vite / esbuild	bun build
4	テスト	Jest / Vitest	bun test
5	スクリプト実行	npx	bun x

課題

従来のツールチェーンにおける問題点

Node.js エコシステムで開発を行う際、開発者は以下のような課題に直面します。

インストール速度の遅さ

npm や yarn を使った依存関係のインストールは、プロジェクトが大きくなるほど時間がかかります。特に CI/CD 環境では、毎回のビルドでインストール時間が積み重なり、開発サイクルを遅延させる要因となっていました。

typescriptCopy code// package.json の例
{
  "dependencies": {
    "react": "^18.2.0",
    "next": "^14.0.0",
    // ...数十から数百の依存関係
  }
}

上記のような構成で npm install を実行すると、数分かかることも珍しくありません。

コマンドの複雑さと学習コスト

npm、yarn、pnpm それぞれで微妙にコマンドが異なり、プロジェクトごとに使い分ける必要があります。

#	操作	npm	yarn	pnpm	Bun
1	インストール	npm install	yarn	pnpm install	bun install
2	パッケージ追加	npm install <pkg>	yarn add <pkg>	pnpm add <pkg>	bun install <pkg>
3	スクリプト実行	npm run <script>	yarn <script>	pnpm <script>	bun run <script>
4	即時実行	npx <pkg>	yarn dlx <pkg>	pnpm dlx <pkg>	bun x <pkg>

ツールの分散と設定の複雑化

バンドラー（webpack）、テストランナー（Jest）、トランスパイラ（Babel）など、それぞれに設定ファイルが必要で、統合管理が困難です。

luaCopy codeproject/
├── webpack.config.js
├── jest.config.js
├── babel.config.js
├── tsconfig.json
└── package.json

このように複数の設定ファイルを管理する必要があり、初学者にとって大きな障壁となっています。

解決策

Bun による統合的アプローチ

Bun は上記の課題を、以下の 5 つの主要コマンドで解決します。

mermaidCopy codeflowchart LR
  problem["開発における<br/>課題"]

  problem --> slow["インストール<br/>が遅い"]
  problem --> complex["コマンドが<br/>複雑"]
  problem --> tools["ツールが<br/>分散"]

  slow --> install["bun install<br/>高速インストール"]
  complex --> run["bun run<br/>統一実行"]
  complex --> x["bun x<br/>即時実行"]
  tools --> test["bun test<br/>組込テスト"]
  tools --> build["bun build<br/>組込バンドラ"]

  install --> solution["統合された<br/>開発体験"]
  run --> solution
  x --> solution
  test --> solution
  build --> solution

この図が示すように、Bun は各課題に対応する専用コマンドを提供し、開発フローを統一しています。

各コマンドの解決ポイント

bun install：高速で信頼性の高いインストール

従来の npm install と比較して、最大 25 倍高速 なインストールを実現します。

bashCopy code# 基本的なインストール
bun install

bashCopy code# 本番環境用（devDependencies を除外）
bun install --production

bashCopy code# lockfile を厳密に守る（CI/CD 向け）
bun install --frozen-lockfile

これにより、開発開始までの待ち時間を大幅に削減できます。

bun run：シンプルで高速なスクリプト実行

package.json に定義されたスクリプトを、Node.js より高速に実行します。

jsonCopy code// package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "test": "bun test"
  }
}

bashCopy code# 開発サーバーを起動
bun run dev

bashCopy code# ファイル変更を監視して自動再実行
bun run --watch dev

bun x：インストール不要の即時実行

npm の npx に相当しますが、より高速で直感的です。

bashCopy code# create-react-app を即座に実行
bun x create-react-app my-app

bashCopy code# 特定バージョンを指定
bun x prettier@latest --write .

プロジェクトに依存関係を追加せず、一時的にツールを使いたい場合に便利です。

bun test：組み込みテストランナー

Jest ライクな API で、設定ファイル不要でテストを実行できます。

typescriptCopy code// math.test.ts
import { expect, test } from 'bun:test';

test('足し算のテスト', () => {
  expect(1 + 1).toBe(2);
});

bashCopy code# すべてのテストを実行
bun test

bashCopy code# カバレッジを測定
bun test --coverage

外部ライブラリのインストールが不要で、すぐにテストを書き始められます。

bun build：高速バンドラー

esbuild や webpack の代替として、TypeScript や JSX を直接バンドルできます。

bashCopy code# 基本的なビルド
bun build ./src/index.ts --outdir ./dist

bashCopy code# 本番用に最適化
bun build ./src/index.ts --outdir ./dist --minify --target browser

設定ファイル不要で、CLI オプションだけで柔軟にカスタマイズできます。

具体例

プロジェクト初期化から本番デプロイまでのワークフロー

実際の開発フローで Bun の主要コマンドをどう使うか、段階的に見ていきましょう。

ステップ 1：プロジェクトのセットアップ

新規プロジェクトを作成し、依存関係をインストールします。

bashCopy code# Next.js プロジェクトを作成
bun x create-next-app@latest my-project

bashCopy code# プロジェクトディレクトリに移動
cd my-project

bashCopy code# 依存関係をインストール
bun install

この時点で、npm と比較して 数倍高速 にインストールが完了します。

ステップ 2：開発サーバーの起動

package.json に定義されたスクリプトを実行します。

jsonCopy code// package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

bashCopy code# 開発サーバーを起動
bun run dev

ブラウザで http:​/​​/​localhost:3000 を開くと、アプリケーションが表示されます。

ステップ 3：パッケージの追加

開発中に新しいライブラリが必要になった場合、その場で追加できます。

bashCopy code# UI ライブラリを追加
bun install @radix-ui/react-dialog

bashCopy code# 開発用の型定義を追加
bun install -d @types/node

インストール後、すぐにコード内で使用できます。

typescriptCopy code// app/page.tsx
import * as Dialog from '@radix-ui/react-dialog';

export default function Home() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>ダイアログを開く</Dialog.Trigger>
      {/* ...以降の実装 */}
    </Dialog.Root>
  );
}

ステップ 4：テストの作成と実行

Bun の組み込みテストランナーでユニットテストを書きます。

typescriptCopy code// lib/utils.ts
export function add(a: number, b: number): number {
  return a + b;
}

export function multiply(a: number, b: number): number {
  return a * b;
}

typescriptCopy code// lib/utils.test.ts
import { expect, test, describe } from 'bun:test';
import { add, multiply } from './utils';

describe('算術関数のテスト', () => {
  test('add は2つの数値を正しく加算する', () => {
    expect(add(2, 3)).toBe(5);
    expect(add(-1, 1)).toBe(0);
  });

  test('multiply は2つの数値を正しく乗算する', () => {
    expect(multiply(2, 3)).toBe(6);
    expect(multiply(-2, 3)).toBe(-6);
  });
});

bashCopy code# すべてのテストを実行
bun test

bashCopy code# 特定のファイルのみテスト
bun test lib/utils.test.ts

bashCopy code# ファイル変更を監視して自動再実行
bun test --watch

テスト結果は以下のように表示されます。

iniCopy codebun test v1.0.0

lib/utils.test.ts:
✓ 算術関数のテスト > add は2つの数値を正しく加算する [0.50ms]
✓ 算術関数のテスト > multiply は2つの数値を正しく乗算する [0.30ms]

 2 pass
 0 fail
 2 expect() calls
Ran 2 tests across 1 files. [100.00ms]

ステップ 5：本番用ビルド

Next.js の場合は bun run build を使いますが、カスタムスクリプトやライブラリの場合は bun build を使います。

bashCopy code# Next.js のビルド
bun run build

bashCopy code# カスタムスクリプトのバンドル
bun build ./src/index.ts --outdir ./dist --target node

bashCopy code# ブラウザ向けに最適化してビルド
bun build ./src/app.tsx --outdir ./public --target browser --minify --sourcemap

ビルドが完了すると、指定したディレクトリに最適化されたファイルが出力されます。

arduinoCopy codedist/
├── index.js
└── index.js.map

ステップ 6：本番環境の起動

bashCopy code# 本番サーバーを起動
bun run start

これで本番環境と同じ設定でアプリケーションが稼働します。

CLI ツールの一時実行例

プロジェクトに常駐させる必要のないツールは、bun x で即座に実行できます。

コードフォーマッターの実行

bashCopy code# Prettier でコードを整形
bun x prettier --write "src/**/*.{ts,tsx,js,jsx}"

リンターの実行

bashCopy code# ESLint でコードをチェック
bun x eslint src/

パッケージバージョンの確認

bashCopy code# TypeScript のバージョンを確認
bun x typescript --version

これらはプロジェクトの依存関係に追加せず、必要なときだけ実行できるため、package.json をクリーンに保てます。

CI/CD 環境での活用例

GitHub Actions で Bun を使う場合の設定例です。

yamlCopy code# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      # リポジトリをチェックアウト
      - uses: actions/checkout@v4

      # Bun をセットアップ
      - uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      # 依存関係をインストール（lockfile を厳守）
      - name: Install dependencies
        run: bun install --frozen-lockfile

      # テストを実行
      - name: Run tests
        run: bun test

      # ビルドを実行
      - name: Build
        run: bun run build

--frozen-lockfile オプションを使うことで、開発環境と完全に同じバージョンの依存関係でテスト・ビルドを実行できます。

エラー対処例

実際の開発で遭遇しやすいエラーと解決方法を紹介します。

エラー 1：lockfile の不整合

エラーコード: error: lockfile had changes, but lockfile is frozen

エラーメッセージ:

vbnetCopy codeerror: lockfile had changes, but lockfile is frozen

発生条件: CI/CD 環境で --frozen-lockfile を使用しているが、ローカルの bun.lockb が最新でない場合に発生します。

解決方法:

1. ローカルで依存関係を再インストール
2. lockfile をコミット

bashCopy code# ローカルで実行
bun install

bashCopy code# 変更をコミット
git add bun.lockb
git commit -m "Update lockfile"
git push

エラー 2：パッケージが見つからない

エラーコード: error: module not found "react"

エラーメッセージ:

luaCopy codeerror: module not found "react"

発生条件: package.json に記載されているパッケージが node_modules にインストールされていない場合です。

解決方法:

1. 依存関係を再インストール

bashCopy codebun install

2. それでも解決しない場合は、node_modules を削除して再インストール

bashCopy coderm -rf node_modules
bun install

エラー 3：テストのタイムアウト

エラーコード: error: test timed out after 5000ms

エラーメッセージ:

bashCopy codeerror: test timed out after 5000ms

発生条件: 非同期処理を含むテストで、デフォルトのタイムアウト時間（5 秒）を超えた場合に発生します。

解決方法:

1. テストのタイムアウト時間を延長

bashCopy codebun test --timeout 10000

2. または、テストファイル内で個別に設定

typescriptCopy codeimport { test } from 'bun:test';

test(
  '時間のかかる処理',
  async () => {
    // ... 処理
  },
  { timeout: 10000 }
); // 10秒に延長

エラー 4：ビルド時のメモリ不足

エラーコード: JavaScript heap out of memory

エラーメッセージ:

bashCopy codeFATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

発生条件: 大規模なプロジェクトをビルドする際、メモリが不足する場合があります。

解決方法:

1. 環境変数でメモリ上限を引き上げ

bashCopy codeexport NODE_OPTIONS="--max-old-space-size=4096"
bun build ./src/index.ts --outdir ./dist

2. または、不要なファイルをビルド対象から除外

bashCopy codebun build ./src/index.ts --outdir ./dist --ignore "**/*.test.ts"

応用的な使用例

環境変数を使った実行

開発環境と本番環境で異なる設定を使う場合、環境変数ファイルを切り替えられます。

bashCopy code# 開発環境用
bun run --env-file .env.development dev

bashCopy code# 本番環境用
bun run --env-file .env.production start

ファイル監視による自動再実行

TypeScript ファイルを編集するたびに自動でビルドを実行します。

bashCopy codebun run --watch build

カバレッジレポートの生成

テストカバレッジを測定し、どの部分がテストされていないかを確認できます。

bashCopy codebun test --coverage

実行後、以下のようなレポートが表示されます。

sqlCopy code---------------------------------------------|---------|----------|---------|
File                                          | % Stmts | % Branch | % Lines |
---------------------------------------------|---------|----------|---------|
All files                                     |   85.5  |   78.2   |   85.5  |
 lib                                          |   92.3  |   88.9   |   92.3  |
  utils.ts                                    |   92.3  |   88.9   |   92.3  |
 src                                          |   78.6  |   66.7   |   78.6  |
  index.ts                                    |   78.6  |   66.7   |   78.6  |
---------------------------------------------|---------|----------|---------|

複数エントリーポイントのビルド

複数のファイルを同時にバンドルする場合は、以下のように指定します。

bashCopy codebun build ./src/index.ts ./src/worker.ts --outdir ./dist

これにより、dist​/​index.js と dist​/​worker.js が生成されます。

まとめ

この記事では、Bun の主要 5 コマンド（bun install、bun run、bun x、bun test、bun build）を、実務で使える形で網羅的に解説しました。

Bun は単なる「速いツール」ではなく、開発フロー全体を統一し、学習コストを下げ、生産性を向上させる統合プラットフォームです。従来は npm、webpack、Jest など複数のツールを組み合わせる必要がありましたが、Bun ならこれらすべてを一貫したコマンド体系で扱えます。

特に以下のような場面で Bun の恩恵を受けられます。

• プロジェクト初期化: bun install の高速インストールで、待ち時間を削減
• 開発フロー: bun run --watch でファイル変更を即座に反映
• CI/CD 環境: bun install --frozen-lockfile で依存関係を厳密に管理
• テスト実行: bun test --coverage で設定不要のテスト環境を構築
• 本番ビルド: bun build --minify で最適化されたバンドルを生成

この記事で紹介した早見表を手元に置いておけば、コマンドやオプションを迷うことなく、スムーズに開発を進められるはずです。

Bun はまだ進化を続けているツールですので、今後も新機能やパフォーマンス改善が期待できます。ぜひ、日々の開発フローに Bun を取り入れて、快適な開発体験を実感してください。

関連リンク

• Bun 公式サイト
• Bun 公式ドキュメント
• Bun GitHub リポジトリ
• Bun CLI リファレンス
• Bun Test ドキュメント
• Bun Build ドキュメント