Bun 完全ガイド【2026年最新】｜Bun 1.3 対応・Runtime / Package Manager / Bundler / Test Runner 四位一体・Bun.sql / Bun.redis / Bun.s3 / Bun.$ / Workspaces & Catalog・Node.js 移行まで解説

# 公式 curl（/usr/local/bin に 1 バイナリで入る）
curl -fsSL https://bun.sh/install | bash

# Homebrew でも可
brew install oven-sh/bun/bun

# Windows（ネイティブサポート。PowerShell）
powershell -c "irm bun.sh/install.ps1 | iex"

# バージョン確認
bun --version   # 1.3.x

# 更新
bun upgrade

bun init my-app
cd my-app

# 生成される構成
# ├── .gitignore
# ├── bun.lock          ← JSONC 形式のロックファイル
# ├── index.ts
# ├── package.json
# ├── README.md
# └── tsconfig.json

# そのまま実行
bun run index.ts

# 1) npm / pnpm / yarn の成果物を退避（バックアップ）
mv node_modules node_modules.bak
mv package-lock.json package-lock.json.bak  # あれば

# 2) Bun で再インストール（bun.lock が生成される）
bun install

# 3) スクリプトはそのまま動く
bun run dev

{
  "lockfileVersion": 1,
  "workspaces": {
    "": {
      "name": "my-app",
      "dependencies": { "hono": "4.9.1" }
    }
  },
  "packages": [
    ["hono@4.9.1", /* tarball */, "sha512-..."],
    ["@types/bun@1.3.0", /* devDep */, "sha512-..."]
  ]
}

# すべての依存をインストール
bun install                       # 省略可: bun i

# 追加（--save, --save-dev, --save-peer 等も対応）
bun add hono
bun add -d vitest                 # devDependencies

# 削除
bun remove hono

# 依存更新状況を可視化
bun outdated

# 特定ライブラリだけ更新
bun update zod

# ローカル npm パッケージをパブリッシュ
bun publish

# パッチ適用（@types/node のバグ回避等）
bun patch @types/node
bun patch --commit @types/node

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"]
  },
  "catalogs": {
    "react19": {
      "react":     "19.2.0",
      "react-dom": "19.2.0"
    }
  }
}

{
  "dependencies": {
    "react":     "catalog:react19",
    "react-dom": "catalog:react19"
  }
}

# .ts / .tsx を直接実行（tsc / ts-node 不要）
bun run index.ts

# JSX でも OK
bun run App.tsx

# --hot で擬似 HMR（ファイル変更で関数単位再読み込み）
bun --hot index.ts

# --watch はプロセス再起動（nodemon 相当）
bun --watch index.ts

# package.json の scripts
bun run dev        # == "dev" スクリプト実行

# 複数 workspace で並列実行（1.3+）
bun run --filter="*" dev

import { serve } from "bun";

const server = serve({
  port: 3000,
  // 静的ルート: Bun がキャッシュして高速配信
  static: {
    "/health": new Response("ok"),
    "/version": Response.json({ bun: Bun.version }),
    "/legacy": Response.redirect("/new", 301),
  },
  // 動的ハンドラ
  async fetch(req) {
    const url = new URL(req.url);
    if (url.pathname === "/hello") {
      return Response.json({ message: "hello bun" });
    }
    return new Response("Not Found", { status: 404 });
  },
});

console.log(`listening on ${server.url}`);

// ランタイム差し替え（コード変更なしで静的ルート更新）
setInterval(() => {
  server.reload({
    static: { "/": new Response(`updated at ${new Date().toISOString()}`) },
  });
}, 1000);

serve({
  port: 3001,
  fetch(req, server) {
    if (server.upgrade(req)) return;     // WebSocket にアップグレード
    return new Response("HTTP route");
  },
  websocket: {
    open(ws) { ws.send("hello"); },
    message(ws, msg) { ws.send(`echo: ${msg}`); },
    close(ws) { console.log("closed"); },
  },
});

import { sql } from "bun";

// 環境変数から DATABASE_URL を拾う
// postgres://user:pass@host:5432/db

type User = { id: number; name: string; age: number };

// INSERT（複数行）
const users = [
  { name: "Alice", age: 25 },
  { name: "Bob",   age: 65 },
];
await sql`INSERT INTO users ${sql(users)}`;

// SELECT
const seniors = await sql<User[]>`
  SELECT id, name, age
  FROM   users
  WHERE  age >= ${65}
`;

// UPDATE（動的 WHERE）
await sql`
  UPDATE users SET name = ${"Alice2"}
  WHERE  id = ${seniors[0].id}
`;

// DELETE
await sql`DELETE FROM users WHERE age < ${20}`;

// 明示的な接続プール・型パラメータ
const db = new Bun.SQL({
  url: process.env.DATABASE_URL,
  max: 10,                   // プール上限
  idle_timeout: 30,
  connection_timeout: 5,
});
const rows = await db`SELECT 1 AS ok`;

await sql.begin(async (tx) => {
  await tx`UPDATE accounts SET balance = balance - 100 WHERE id = ${1}`;
  await tx`UPDATE accounts SET balance = balance + 100 WHERE id = ${2}`;
  // コールバック内で throw したら自動 ROLLBACK、正常終了で COMMIT
});

import { redis } from "bun";

// REDIS_URL 環境変数から自動接続
// redis://default:pass@host:6379

await redis.set("user:1", JSON.stringify({ id: 1, name: "Alice" }));
await redis.expire("user:1", 60);

const raw = await redis.get("user:1");
const user = raw ? JSON.parse(raw) : null;

// インクリメント
const count = await redis.incr("visits:2026-04-22");

// 未対応コマンドは send() でエスケープ
const info = await redis.send("INFO", ["server"]);

// 並列発行（内部で自動パイプライニング）
const [ok1, ok2, val] = await Promise.all([
  redis.set("a", "1"),
  redis.set("b", "2"),
  redis.get("a"),
]);

import { s3 } from "bun";

// 環境変数 S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY / S3_BUCKET / S3_ENDPOINT など
// Cloudflare R2 なら S3_ENDPOINT に R2 エンドポイントを指定

// 読み込み
const text = await s3.file("reports/2026-04.md").text();
const bin  = await s3.file("images/logo.png").arrayBuffer();

// 書き込み
await s3.file("logs/app.log").write("hello\n");

// 大きなファイル（ストリーミング）
const writer = s3.file("large-export.csv").writer();
for await (const chunk of generateChunks()) writer.write(chunk);
await writer.end();

// 署名付き URL（期限付き共有リンク）
const url = s3.presign("private/doc.pdf", {
  expiresIn: 3600,        // 1h
  acl: "public-read",
});

// Bun.serve の静的ルートにそのまま流せる
serve({
  static: { "/favicon.ico": s3.file("public/favicon.ico") },
  fetch() { return new Response("ok"); },
});

import { $ } from "bun";

// 基本実行（終了コードが非 0 なら throw）
await $`echo "hello"`;

// 変数を安全に展開（シェルインジェクション対策込み）
const branch = "main";
await $`git checkout ${branch}`;

// stdout を文字列として受け取る
const tag = (await $`git describe --tags --abbrev=0`.text()).trim();

// JSON として
const pkg = await $`cat package.json`.json();

// パイプも書ける
await $`ls -la | grep -v node_modules`;

// 終了コード制御
const res = await $`test -d dist`.nothrow();
if (res.exitCode !== 0) await $`mkdir -p dist`;

// 環境変数注入
await $`npm publish`.env({ NPM_TOKEN: process.env.NPM_TOKEN });

// カレントディレクトリ変更
await $`pwd`.cwd("/tmp");

import { expect, test, describe, mock } from "bun:test";

describe("math", () => {
  test("add", () => {
    expect(2 + 3).toBe(5);
  });

  test("floating point", () => {
    expect(0.1 + 0.2, "丸め誤差チェック").toBeCloseTo(0.3);
  });

  test("inline snapshot", () => {
    const config = { env: "prod", retries: 3 };
    expect(config).toMatchInlineSnapshot(`
      {
        "env": "prod",
        "retries": 3,
      }
    `);
  });
});

// モック
const fetchMock = mock(() => Promise.resolve({ ok: true }));
expect(fetchMock).toHaveReturned();

// フィルタ: このテストだけ走らせたい時
test.only("focused", () => {
  expect(1).toBe(1);
});

# JUnit 形式でレポート出力（CI 向け）
bun test --reporter=junit --reporter-outfile=test-results.xml

# カバレッジ計測（lcov 出力）
bun test --coverage --coverage-reporter=lcov

# 単一ファイル・パターン指定
bun test src/auth/*.test.ts
bun test --test-name-pattern="should login"

# VS Code テスト統合（1.3+）
# Bun: Test エクスプローラに直接統合されるようになった

# ブラウザ向けにバンドル（Tree-shaking 込み）
bun build ./src/main.tsx --outdir ./dist --target browser --minify

# Node.js 向けバンドル
bun build ./src/server.ts --outdir ./dist --target node

# Bun 向けスタンドアロンバイナリ（--compile）
bun build --compile ./src/cli.ts --outfile mycli

# クロスコンパイル（1.2+）
bun build --compile --target=bun-linux-x64       ./src/cli.ts --outfile mycli-linux
bun build --compile --target=bun-windows-x64     ./src/cli.ts --outfile mycli.exe
bun build --compile --target=bun-darwin-arm64    ./src/cli.ts --outfile mycli-mac

# Bytecode キャッシュ付き（起動高速化）
bun build --bytecode --compile ./src/cli.ts --outfile mycli

# 環境変数を注入（PUBLIC_ プレフィックスのみ）
bun build ./src/app.tsx --env="PUBLIC_*"

# console.* を落とす
bun build ./src/app.ts --drop=console --minify

# 外部パッケージを bundle 対象外にする
bun build ./src/server.ts --packages=external

// server.ts
import homepage from "./index.html";

Bun.serve({
  routes: {
    "/": homepage,                 // HTML/CSS/JS/TSX を自動バンドル
    "/api/hello": () => Response.json({ hello: "bun" }),
  },
  development: true,               // HMR 有効
});

// index.html 側で <script src="./app.tsx"></script> と書けば
// 自動的に TSX がバンドルされてブラウザに配信される

FROM oven/bun:1.3-alpine AS deps
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile --production

FROM oven/bun:1.3-alpine
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NODE_ENV=production
EXPOSE 3000
CMD ["bun", "run", "src/server.ts"]

# CI で各 OS ターゲットを build
bun build --compile --target=bun-linux-x64 --minify --bytecode \
  ./src/server.ts --outfile server-linux

# 実行（コンテナにも Node.js 不要）
scp server-linux user@host:/opt/app/
ssh user@host "/opt/app/server-linux"