Bunのworkspacesで、複数のパッケージをまとめて管理する方法

​​Bun​package.json,TypeScript,パッケージ管理,モノレポ

Bun の workspaces を使うと、API サーバー、フロントエンド、両方で使う共通ライブラリのような複数のパッケージを1つのリポジトリ(モノレポ)に置いたまま、ルートで bun install を1回実行するだけで、全部の依存を入れられます。共通ライブラリは workspace:* で参照すれば、npm に公開しなくても、ほかのパッケージから import できます。

ここでは、ワークスペースが3つある小さなモノレポを検証環境に作り、設定の書き方、bun install で node_modules がどうなるか、--filter でスクリプトをまとめて実行したときの順番を確かめました。出力は検証で得たものを載せ、一部を略したところは、その場で書き添えています。

補足

検証環境は Ubuntu 24.04(x86_64)、Bun 1.4.4 です。パッケージは、2026年11月15日に標準のレジストリ(registry.npmjs.org)から取得しました。catalog(バージョンをまとめて決める機能)、selfContained、--parallel と --sequential、bun update と bun outdated の --filter、npm への公開、Windows と macOS は試していません。

ルートの package.json に workspaces を書く

作ったモノレポのファイルは、次の6つです。packages/utils が共通ライブラリ、apps/api と apps/web がそれを使う側という想定です。

txt
$ find . -type f | sort
./apps/api/index.ts
./apps/api/package.json
./apps/web/package.json
./package.json
./packages/utils/package.json
./packages/utils/src/index.ts

ルートの package.json には、ワークスペースとして扱うフォルダを workspaces に並べます。* などの glob が使えます。

json
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["packages/*", "apps/*"]
}

それぞれのワークスペースには、自分の package.json を置きます。公式ドキュメントの workspaces のページによると、ワークスペースには name が必要で、name のない package.json は飛ばされます。ここでは @demo/ で始まる名前にしました。

共通ライブラリの @demo/utils は、TypeScript のファイルを exports でそのまま指しています。Bun で実行するなら、ビルドしたファイルを用意しなくても読み込めます。

json
{
  "name": "@demo/utils",
  "version": "1.0.0",
  "type": "module",
  "exports": "./src/index.ts",
  "scripts": {
    "build": "echo utils build start && sleep 1 && echo utils build done"
  },
  "dependencies": {
    "zod": "^3.25.0"
  }
}
ts
export function greet(name: string): string {
  return `こんにちは、${name}さん`;
}

build は、あとでスクリプトの実行順を見るためのものです。わざと sleep 1 で1秒かかるようにしています。

workspace:* でほかのワークスペースを参照する

apps/api から @demo/utils を使うときは、dependencies のバージョンの代わりに workspace:* と書きます。

json
{
  "name": "@demo/api",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "echo api build",
    "start": "bun index.ts"
  },
  "dependencies": {
    "@demo/utils": "workspace:*",
    "zod": "^3.25.0"
  }
}
ts
import { greet } from "@demo/utils";
console.log(greet("Bun"));

apps/web は @demo/utils を使わず、zod だけをメジャーバージョン 4 で入れる設定にしました。api と utils は zod 3、web は zod 4 という、バージョンの違う依存が同じリポジトリに混ざる形です。

json
{
  "name": "@demo/web",
  "version": "1.0.0",
  "scripts": {
    "build": "echo web build"
  },
  "dependencies": {
    "zod": "^4.0.0"
  }
}

ルートで bun install を1回実行する

ルートのフォルダで bun install を実行すると、3つのワークスペースの依存がまとめて入り、bun.lock はルートにできました。

txt
$ bun install
bun install v1.4.4 (38afee6c8)
Saved lockfile

2 packages installed [9.00ms]

bun.lock には、ワークスペースごとの依存が workspaces の下に並びます。packages の下では、@demo/utils は workspace:packages/utils、つまりリポジトリの中のフォルダとして記録されていました。zod は 3.25.76 と、web 用の 4.6.7 の2つが記録されています。

txt
  "packages": {
    "@demo/api": ["@demo/api@workspace:apps/api"],

    "@demo/utils": ["@demo/utils@workspace:packages/utils"],

    "@demo/web": ["@demo/web@workspace:apps/web"],

    "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXs(以下略)"],

    "@demo/web/zod": ["zod@4.6.7", "", {}, "sha512-g8W2D2kU6a8u(以下略)"],
  }

この状態で api を実行すると、@demo/utils の関数がそのまま呼べました。

txt
$ (cd apps/api && bun run start)
$ bun index.ts
こんにちは、Bunさん

packages/utils/src/index.ts の「こんにちは」を「やあ」に書き換えて、もう一度実行すると、bun install をやり直さなくても「やあ、Bunさん」に変わりました。理由は次の節で見る node_modules の中身にあります。

node_modules は各ワークスペースの中にリンクで作られる

bun install のあとのルートの node_modules には、.bun というフォルダが1つあるだけでした。

txt
$ ls -A node_modules
.bun
$ ls node_modules/.bun
node_modules
zod@3.25.76
zod@4.6.7

各ワークスペースの node_modules には、自分の package.json に書いた依存だけが、シンボリックリンクで置かれていました(ls -l の出力から、日時などの列と total の行を除いています)。

txt
apps/api/node_modules:
@demo
zod -> ../../../node_modules/.bun/zod@3.25.76/node_modules/zod

apps/api/node_modules/@demo:
utils -> ../../../../packages/utils

apps/web/node_modules:
zod -> ../../../node_modules/.bun/zod@4.6.7/node_modules/zod

packages/utils/node_modules:
zod -> ../../../node_modules/.bun/zod@3.25.76/node_modules/zod

@demo/utils は packages/utils のフォルダそのものへのリンクです。そのため、utils のソースを書き換えると、api からはすぐに新しい内容が見えます。zod は、api と utils が 3.25.76 を、web が 4.6.7 を指していて、バージョンの違うものが共存しています。

これは「isolated」という入れ方(linker)です。公式ドキュメントの isolated installs のページによると、新しく作るモノレポ(bun.lock の configVersion が 1)では isolated が既定です。ワークスペースを使わない普通のプロジェクトや、Bun 1.3.2 より前に作ったプロジェクトでは、npm と同じように依存をルートの node_modules に集める「hoisted」が既定になります。今回の bun.lock にも "configVersion": 1 が入っていました。

ほかのワークスペースの依存は import できない

isolated では、package.json に書いていないパッケージは、ほかのワークスペースが入れたものでも読み込めませんでした。utils に ms を足し(cd packages/utils && bun add ms@2.1.3)、api のほうから package.json に書かないまま ms を読み込んでみました。

ts
import ms from "ms";
console.log(ms(60000));
txt
$ (cd apps/api && bun phantom.ts)
error: Cannot find package 'ms' from '/path/to/my-monorepo/apps/api/phantom.ts'

Bun v1.4.4 (Linux x64)

(パスは、検証環境のものを /path/to/my-monorepo に置き換えています。)

同じ状態で、node_modules を消してから bun install --linker hoisted で入れ直すと、ルートの node_modules に ms と zod 3.25.76 が集まり、ワークスペース自身も node_modules/@demo/ に並びました。zod 4.6.7 だけは apps/web/node_modules に置かれました。

txt
$ ls node_modules node_modules/@demo
node_modules:
@demo
ms
zod

node_modules/@demo:
api
utils
web

この入れ方だと、api の package.json に書いていない ms が読み込めてしまいます。

txt
$ (cd apps/api && bun phantom.ts)
1m

isolated でも、ルートの package.json に書いた依存は別です。ワークスペース2つで作り直したモノレポで、ルートに bun add -d ms@2.1.3 で ms を足すと、ルートの node_modules に ms が置かれ、宣言していない api からも読み込めて 1m と出ました。isolated で書き忘れがエラーになったのは、ほかのワークスペースにだけ入っている依存の場合です。isolated installs のページにも、install.hoist = false にした場合の注意として、ルートの node_modules に置かれたパッケージは、store の中のどのパッケージからも解決できると書かれています。

ルートから1つのワークスペースに依存を足す

依存を足すときは、そのワークスペースのフォルダへ移らなくても、ルートで --filter にワークスペースの名前を渡せば足せます。

txt
$ bun add dayjs --filter '@demo/web'
bun add v1.4.4 (38afee6c8)
Saved lockfile

installed dayjs@1.11.23

1 package installed [6.00ms]

dayjs は apps/web/package.json にだけ "dayjs": "^1.11.23" で追加され、ルートと api、utils の package.json には入りませんでした。公式ドキュメントの –filter のページによると、bun add のようなパッケージ管理のコマンドでは、--filter をサブコマンドのあとに置きます。

–filter でスクリプトをまとめて実行する

bun --filter '*' build のように実行すると、名前が合うワークスペースの build をまとめて実行します。端末で実行すると、ワークスペースごとに区切った画面が出て、実行中は表示が書き換わっていきます。次の2枚は、検証で記録した端末の出力を描き直したものです。

bun --filter '*' build を端末で実行している途中の画面。utils が Running...、web が Done in 2 ms、api が Waiting for 1 other script(s) と表示されている
実行の途中。api は utils の build が終わるのを待っている

web はすぐに終わりましたが、api は「Waiting for 1 other script(s)」と出て、まだ始まっていません。api は @demo/utils に依存しているので、utils の build が終わるのを待ちます。公式ドキュメントの –filter のページにも、ほかのワークスペースに依存しているスクリプトは、依存先のスクリプトが終わってから始まると書かれています。utils の build が終わると、api が動き出しました。

bun --filter '*' build が終わったときの画面。utils が Done in 1.00 s、web と api も Done と表示されている
3つとも終わったところ

パイプで別のコマンドに出力を渡したとき(| cat)は、この画面にならず、行の頭にワークスペースとスクリプトの名前が付いた形で出ました。こちらのほうが順番を追いやすいです。

txt
$ bun --filter '*' build | cat
@demo/utils build: utils build start
@demo/web build: web build
@demo/web build: Exited with code 0
@demo/utils build: utils build done
@demo/utils build: Exited with code 0
@demo/api build: api build
@demo/api build: Exited with code 0

utils と web は待たずに始まり、api は utils が終わってから始まっています。bun run --workspaces build でも、出力は同じでした。

実行するワークスペースを絞る

--filter には、名前のほかにフォルダのパスや、依存の関係も書けます。検証では次のようになりました。

指定 build が実行されたワークスペース
'@demo/api...' utils、api(api と、api が依存しているもの)
'...@demo/utils' utils、api(utils と、utils に依存しているもの)
'./apps/*' web、api(apps の下のフォルダ)
'*' --filter '!@demo/web' utils、api(web を除く)

たとえば api だけを動かしたいけれど、その前に共通ライブラリのビルドも済ませたい、というときは '@demo/api...' が使えます。

txt
$ bun --filter '@demo/api...' build | cat
@demo/utils build: utils build start
@demo/utils build: utils build done
@demo/utils build: Exited with code 0
@demo/api build: api build
@demo/api build: Exited with code 0

どのワークスペースにも合わない名前を渡すと、error: No workspace packages matched the filter "nothing" と出て、終了コードは 1 でした。

1つが失敗しても、ほかは続く

utils の build を exit 1 で失敗させて、同じように実行しました。

txt
$ bun --filter '*' build | cat
@demo/web build: web build
@demo/utils build: utils build start
@demo/web build: Exited with code 0
@demo/utils build: Exited with code 1
@demo/api build: api build
@demo/api build: Exited with code 0

utils が失敗しても、utils を待っていた api の build は実行されました。全体の終了コードは 1 です。CI では終了コードで失敗が分かりますが、依存先のビルドが失敗したまま後ろのスクリプトが動く点には気を付けてください。

公開するときは workspace:* が実際のバージョンに置き換わる

workspace:* は、リポジトリの中でだけ意味を持つ書き方です。api のフォルダで bun pm pack を実行して tgz ファイルを作り、中の package.json を取り出しました。公式ドキュメントの bun pm のページによると、bun pm pack は npm に公開されるファイルを、npm pack と同じ決まりで tgz にまとめるコマンドです。

json
{
  "name": "@demo/api",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "echo api build",
    "start": "bun index.ts"
  },
  "dependencies": {
    "@demo/utils": "1.0.0",
    "zod": "^3.25.0"
  }
}

"@demo/utils": "workspace:*" が、utils の package.json の version である "1.0.0" に置き換わっていました。公式ドキュメントによると、workspace:^ なら ^1.0.0 のように、^ や ~ を付けたバージョンになります。

​Posted by 86