Bun への移行について

このページでは、本プロジェクトが従来の Node.js（npm / yarn / pnpm）ベースの環境から、超高速な JavaScript ランタイムである Bun へ移行した理由と、具体的な移行手順をまとめています。

開発効率および CI/CD の速度向上を目的としており、全メンバーが同じ動作環境を利用できるよう、以下の手順に従ってセットアップを行ってください。

1. 移行の背景

本プロジェクトでは長らく Node.js と npm/yarn/pnpm を使用していましたが、以下の課題がありました。

• インストール速度が全体的に遅い
• 大規模依存環境でのビルド時間が増大
• CI/CD の実行時間が長い
• プロジェクト間で依存解決の差分が発生しやすい
• パッケージマネージャが複数あり、環境統一が難しい

Bun は高速な JavaScript ランタイム兼ツールチェーンであり、以下のメリットがあります。

• インストールが npm の 20倍近く高速
• bun install が非常に高速で、依存解決も安定
• bun run によるスクリプト実行が高速
• node 互換 API が充実し、移行コストが低い
• 単一ツールで「ランタイム」「パッケージ管理」「テスト」を統合できる

これらの理由から、プロジェクト全体として Bun へ移行することに決定しました。

---

Bun のセットアップ方法

1. ローカル環境へ Bun をインストール

公式インストーラを推奨します。

curl -fsSL [https://bun.sh/install](https://bun.sh/install) | bash

Windows の場合は PowerShell で以下を実行します。

powershell -c "irm bun.sh/install.ps1 | iex"

インストール後、必ずバージョンを確認してください。

bun --version

---

2. 旧パッケージマネージャの利用停止

npm / yarn / pnpm と混在すると環境が壊れるため、今後は以下を使用しないでください。

• npm install
• yarn add
• pnpm install

今後はすべて Bun を使用します。

---

3. 依存関係の再インストール

Bun は独自のロックファイル bun.lockbもしくはbun.lock を生成します。
プロジェクトルートで以下を実行してください。

bun install

依存関係がすべて Bun 形式に再構築されます。

---

4. package.json スクリプトの更新

Bun 実行環境に統一するため、一部スクリプトを置き換えています。

例：

{
  "scripts": {
    "dev": "bun run next dev",
    "build": "bun run next build",
    "start": "bun run next start"
  }
}

node や npm run を使用していた箇所は bun run に変更されています。

---

プロジェクト側の変更点

1. CI/CD の Bun 化

GitHub Actions では、Bun の公式セットアップアクションを使用します。

- name: Install Bun
  uses: oven-sh/setup-bun@v1
  with:
    bun-version: latest

- name: Install dependencies
  run: bun install

今後、CI はすべて Bun 前提で構築されています。

---

2. Next.js 開発環境の高速化

Bun の導入により、以下の恩恵があります。

• dev server 起動速度が向上
• ビルド時間が大きく短縮
• プレビューや Cloudflare Pages 用ビルドが高速化

Bun 導入後、開発体験が大幅に改善されます。

---

既存コードからの移行時の注意点

Bun は Node.js のほとんどを互換しますが、以下の点に注意してください。

ネイティブ Node.js API の一部は互換性が異なる

特に古い API を使用している場合、動作を確認してください。

node_modules のクリーンアップ推奨

移行時に依存が壊れている場合があります。

rm -rf node_modules
bun install

npm script の一部は書き換えが必要

npm run と書かれている箇所は bun run に修正してください。

---

よくある質問

Q1. Bun と Node.js の両方を使う必要はありますか

不要です。 本プロジェクトでは Bun を標準とし、Node.js の同時利用は想定していません。

Q2. Docker で使う場合どうなりますか

Bun 公式イメージがあります。

FROM oven/bun

こちらを利用してください。

Q3. npm パッケージはそのまま使えますか

大半は互換しますが、一部ネイティブ拡張の依存を含むものは注意が必要です。