index

npm workspaces

npm v7から導入された機能。モノレポの依存関係をいい感じに管理できる。

まずは基本的なnpm workspacesの使い方

ほぼドキュメント通りだがハンズオンするとイメージが湧きやすいのでやる。

まずnpm initでnpmプロジェクトの雛形を作る。

workspaceを作っていく。まずはunjs/cittyのissueをofetchで取得するリポジトリaを作ってみる。

npm init -w ./packages/aするとこういうのができる。

1
{
2
    "name": "a",
3
    "version": "1.0.0",
4
    "description": "",
5
    "license": "ISC",
6
    "author": "",
7
    "type": "commonjs",
8
    "main": "index.js",
9
    "scripts": {
10
        "test": "echo \"Error: no test specified\" && exit 1"
11
    },
12
}

このワークスペースの中にofetchを入れる。

npm install ofetch -w ./packages/a

するとこうなる。

1
{
2
    "name": "a",
3
    "version": "1.0.0",
4
    "description": "",
5
    "license": "ISC",
6
    "author": "",
7
    "type": "commonjs",
8
    "main": "index.js",
9
    "scripts": {
10
        "test": "echo \"Error: no test specified\" && exit 1"
11
    },
12
    "dependencies": {
13
        "ofetch": "^1.4.1"
14
    }
15
}

今度はプロジェクト全体でzodを使えるようにする。

npm install zod

これでpackage.jsonを見比べると、それぞれで依存関係を管理できていることがわかる。

ここまでの成果物を実行する

1
import { ofetch } from "ofetch";
2
import { parseGitHubIssueResponse } from "./types";
3

4
const fetchIssue = async () => {
5
    const url = "https://api.github.com/repos/unjs/citty/issues?state=open";
6
    const data = await ofetch(url, {
7
        method: "GET",
8
        headers: {
9
            Accept: "application/vnd.github.v3+json",
10
        },
11
    });
12
    const issues = data;
13
    console.log("Fetched issues:", issues);
14
    const parsedIssues = issues.map((issue: unknown) =>
15
        parseGitHubIssueResponse(issue)
16
    );
17
    console.log("Parsed issues:", parsedIssues);
18
};
19

20
fetchIssue();

npm-workspaces % cd ./packages/a
a % npx tsc
a % node index.js

結果、issueが取得できた。

workspaceを増やす

aを作ったのと同じ要領で今度はbを作り、こちらはaxiosを入れてみる。

npm init -w ./packages/b
npm install axios -w b

するとaはofetchが入っていて、bはaxiosが入っているのがわかる。

こちらはaxiosを使ってissueを取得してみる。

1
import axios from "axios";
2
import { parseGitHubIssueResponse } from "./types";
3

4
const fetchIssue = async () => {
5
    const url = "https://api.github.com/repos/unjs/citty/issues?state=open";
6
    try {
7
        const response = await axios.get(url, {
8
            headers: {
9
                Accept: "application/vnd.github.v3+json",
10
            },
11
        });
12
        const issues = response.data;
13
        console.log("Fetched issues:", issues);
14
        const parsedIssues = issues.map((issue: unknown) =>
15
            parseGitHubIssueResponse(issue)
16
        );
17
        console.log("Parsed issues:", parsedIssues);
18
    } catch (error) {
19
        console.error("Error fetching issues:", error);
20
    }
21
};
22

23
fetchIssue();

同じように取得できた。

あとはそれぞれのpackage.jsonにそれぞれでテストを書いたり、必要なnpm scriptを定義したりするとパッケージ単位にコマンドを実行したりできる。

npm run test --workspace=a --workspace=bのように複数のワークスペースも対象にもできる。

ここまでは一見よさげだが、まだ完全体ではない。

ここまでで不完全なところ

まず上のaとbのそれぞれでissueをfetchできたリポジトリの状態を見てほしい。

ルートにある`node_modules`の中身を`require`している

今のプロジェクトの状態でtscしてできたjsをみてほしい。

1
"use strict";
2
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
3
    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
4
    return new (P || (P = Promise))(function (resolve, reject) {
5
        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
6
        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
7
        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
8
        step((generator = generator.apply(thisArg, _arguments || [])).next());
9
    });
10
};
11
Object.defineProperty(exports, "__esModule", { value: true });
12
const ofetch_1 = require("ofetch");
13
const types_1 = require("../types");
14
const fetchIssue = () => __awaiter(void 0, void 0, void 0, function* () {
15
    const url = "https://api.github.com/repos/unjs/citty/issues?state=open";
16
    const data = yield (0, ofetch_1.ofetch)(url, {
17
        method: "GET",
18
        headers: {
19
            Accept: "application/vnd.github.v3+json",
20
        },
21
    });
22
    const issues = data;
23
    console.log("Fetched issues:", issues);
24
    const parsedIssues = issues.map((issue) => (0, types_1.parseGitHubIssueResponse)(issue));
25
    console.log("Parsed issues:", parsedIssues);
26
});
27
fetchIssue();

どうも現状はルートにあるnode_modulesの中身をrequireしているらしい。

つまりこのままだとマイクロサービス(例えばFaaSなど)にaとbのそれぞれをデプロイする場合にもプロジェクト全体を置く必要があることを意味する。なぜならnode_modulesはルートにできているからだ。

`types.ts`が複数できている

ここでaとbのtypes.tsをお見せする。ちなみに内容はどちらも同じだ。

1
import { z } from "zod";
2

3
// Define the schema for a GitHub issue response
4
const GitHubIssueSchema = z.object({
5
    id: z.number(),
6
    node_id: z.string(),
7
    url: z.string().url(),
8
    repository_url: z.string().url(),
9
    labels_url: z.string().url(),
10
    comments_url: z.string().url(),
11
    events_url: z.string().url(),
12
    html_url: z.string().url(),
13
    number: z.number(),
14
    state: z.string(),
15
    title: z.string(),
16
    body: z.string().nullable(),
17
    user: z.object({
18
        login: z.string(),
19
        id: z.number(),
20
        node_id: z.string(),
21
        avatar_url: z.string().url(),
22
        gravatar_id: z.string().nullable(),
23
        url: z.string().url(),
24
        html_url: z.string().url(),
25
        followers_url: z.string().url(),
26
        following_url: z.string(),
27
        gists_url: z.string(),
28
        starred_url: z.string(),
29
        subscriptions_url: z.string().url(),
30
        organizations_url: z.string().url(),
31
        repos_url: z.string().url(),
32
        events_url: z.string(),
33
        received_events_url: z.string().url(),
34
        type: z.string(),
35
        site_admin: z.boolean(),
36
    }),
37
    labels: z.array(
38
        z.object({
39
            id: z.number(),
40
            node_id: z.string(),
41
            url: z.string().url(),
42
            name: z.string(),
43
            color: z.string(),
44
            default: z.boolean(),
45
            description: z.string().nullable(),
46
        })
47
    ),
48
    assignee: z
49
        .object({
50
            login: z.string(),
51
            id: z.number(),
52
            node_id: z.string(),
53
            avatar_url: z.string().url(),
54
            gravatar_id: z.string().nullable(),
55
            url: z.string().url(),
56
            html_url: z.string().url(),
57
            followers_url: z.string().url(),
58
            following_url: z.string(),
59
            gists_url: z.string(),
60
            starred_url: z.string(),
61
            subscriptions_url: z.string().url(),
62
            organizations_url: z.string().url(),
63
            repos_url: z.string().url(),
64
            events_url: z.string(),
65
            received_events_url: z.string().url(),
66
            type: z.string(),
67
            site_admin: z.boolean(),
68
        })
69
        .nullable(),
70
    assignees: z
71
        .array(
72
            z.object({
73
                login: z.string(),
74
                id: z.number(),
75
                node_id: z.string(),
76
                avatar_url: z.string().url(),
77
                gravatar_id: z.string().nullable(),
78
                url: z.string().url(),
79
                html_url: z.string().url(),
80
                followers_url: z.string().url(),
81
                following_url: z.string(),
82
                gists_url: z.string(),
83
                starred_url: z.string(),
84
                subscriptions_url: z.string().url(),
85
                organizations_url: z.string().url(),
86
                repos_url: z.string().url(),
87
                events_url: z.string(),
88
                received_events_url: z.string().url(),
89
                type: z.string(),
90
                site_admin: z.boolean(),
91
            })
92
        )
93
        .nullable(),
94
    comments: z.number(),
95
    created_at: z.string(),
96
    updated_at: z.string(),
97
    closed_at: z.string().nullable(),
98
    author_association: z.string(),
99
    active_lock_reason: z.string().nullable(),
100
});
101

102
// Function to parse and validate the GitHub issue response
103
export const parseGitHubIssueResponse = (response: unknown) => {
104
    const result = GitHubIssueSchema.safeParse(response);
105

106
    if (!result.success) {
107
        console.error("Invalid GitHub issue response:", result.error);
108
        return null;
109
    }
110

111
    return result.data;
112
};

これは完全にDRY原則違反なので、ここで新たにnpm init -w ./packages/typesでパッケージを追加するとしよう。

その下にindex.tsを作り、元のtypes.tsを移植する。結果こうなる。

そしてpackages/b/index.tsはこうなる。

1
import axios from "axios";
2
import { parseGitHubIssueResponse } from "./types";
3
import { parseGitHubIssueResponse } from "../types";
4

5
const fetchIssue = async () => {
6
    const url = "https://api.github.com/repos/unjs/citty/issues?state=open";
7
    try {
8
        const response = await axios.get(url, {
9
            headers: {
10
                Accept: "application/vnd.github.v3+json",
11
            },
12
        });
13
        const issues = response.data;
14
        console.log("Fetched issues:", issues);
15
        const parsedIssues = issues.map((issue: unknown) =>
16
            parseGitHubIssueResponse(issue)
17
        );
18
        console.log("Parsed issues:", parsedIssues);
19
    } catch (error) {
20
        console.error("Error fetching issues:", error);
21
    }
22
};
23

24
fetchIssue();

これをビルドし実行してみると…

確かにissueは取れた。一見いい感じに共通部品を別のパッケージに切り出せたように見える。しかし、「よっしゃこれがTypeScriptのモノレポのパワーやで〜🎉」とはならない。理由はビルドされたJSを見ればわかる。

1
"use strict";
2
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
3
    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
4
    return new (P || (P = Promise))(function (resolve, reject) {
5
        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
6
        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
7
        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
8
        step((generator = generator.apply(thisArg, _arguments || [])).next());
9
    });
10
};
11
var __importDefault = (this && this.__importDefault) || function (mod) {
12
    return (mod && mod.__esModule) ? mod : { "default": mod };
13
};
14
Object.defineProperty(exports, "__esModule", { value: true });
15
const axios_1 = __importDefault(require("axios"));
16
const types_1 = require("../types");
17
const fetchIssue = () => __awaiter(void 0, void 0, void 0, function* () {
18
    const url = "https://api.github.com/repos/unjs/citty/issues?state=open";
19
    try {
20
        const response = yield axios_1.default.get(url, {
21
            headers: {
22
                Accept: "application/vnd.github.v3+json",
23
            },
24
        });
25
        const issues = response.data;
26
        console.log("Fetched issues:", issues);
27
        const parsedIssues = issues.map((issue) => (0, types_1.parseGitHubIssueResponse)(issue));
28
        console.log("Parsed issues:", parsedIssues);
29
    }
30
    catch (error) {
31
        console.error("Error fetching issues:", error);
32
    }
33
});
34
fetchIssue();

const types_1 = require("../types");となっている。つまり単にpackages/typesのモジュールを呼んでいるにすぎない。

そう。これをマイクロサービスなどにデプロイすることを考えると、結局「node_modulesはルートにできている」問題と同じところに帰結する。

解決編

しかしこれらはいずれも全く問題ない。結局どちらの場合もバンドラがないために起こっている問題だからだ。というわけで今回はesbuildを突っ込んで改めてビルドする。

npm-workspaces % npm install --save-dev esbuild
npm-workspaces % cd ./packages/a
a % esbuild index.ts --bundle --platform=node --target=node22 --outdir=dist

すると、

となり、いい感じにビルドしてくれた。

npm workspaces の役割

ここまでで一度npm workspacesの役割を整理する。

パッケージの依存関係管理を一元化できる
ワークスペース間での依存リンク（symlink）を自動で設定
各パッケージの node_modules を共有して効率化

つまり、npm workspacesは「モノレポ構成で依存関係の管理を簡単にする」ための機能。

Turborepo の特徴と利点

一方でTurborepo は npm workspaces や pnpm workspaces をベースにして、追加機能を提供するツール。

追加機能1: 高速なビルドとキャッシュ

タスクの並列・依存解決実行（ビルド、lint、test など）
ローカルキャッシュ + リモートキャッシュ（Vercelと連携）

turbo run build

依存関係を自動解析し、必要な順序で高速ビルド＋キャッシュを活用。

追加機能2: 柔軟なタスク定義

package.json に依存せず、turbo.json でパイプライン定義が可能
例：「lint → build → test」などを順序づけて実行できる

追加機能3: 差分ビルド（Incremental Build）

Gitベースで変更検知
変更があったパッケージだけをビルド・テストする

まとめ

機能	npm workspaces	Turborepo
依存管理	✅	✅（workspaces に依存）
タスクの依存解決	❌	✅
差分ビルド / キャッシュ	❌	✅
リモートキャッシュ	❌	✅（Vercel と連携）
パイプライン定義	❌	✅
CI/CD 最適化	❌	✅

以上から、モノレポが中〜大規模になってきて、

CI の速度を上げたい
差分だけビルド・テストしたい

みたいな段階になってTurborepoは登場するという感じだ。

npm or pnpm のどちらのworkspace機能を使うのか？という話はnpm vs pnpm の話なのでこの記事では扱わないこととする。ただOSSを見てるとほとんどはpnpmを使ってるなという印象がある。

Post to X

Share to Bluesky

再入門: npm workspacesとTurborepo