【入門編】 Project Referencesによる大規模プロジェクトの分割 – TypeScript実践ガイド

こんにちは。フロントエンドの現場で日々コードと格闘しているチーフアーキテクトです。

TypeScriptを使い始めると、最初は「型があって安心！」と感動するものですが、プロジェクトが大きくなるにつれて、こんな悩みが出てきませんか？

「ファイルを一つ保存するたびに、TypeScriptのチェックが終わるまで時間がかかってコーヒーを淹れに行く羽目になる…」
「どこで何が使われているのか、依存関係がスパゲッティ状態になっていて怖い…」

そんな大規模開発の苦しみを解消する、「Project References」という魔法のような仕組みについて、今日はじっくりお話ししましょう。

—

1. なぜプロジェクトを「分割」する必要があるのか？

想像してみてください。あなたは巨大なショッピングモールの設計図を、たった一枚の紙に描こうとしています。
最初はいいんです。でも、お店が増え、通路が増え、電気系統の配線まで書き込んだらどうなるでしょう？消しゴムをかけるだけで一苦労ですよね。

TypeScriptも同じです。`tsconfig.json` という設定ファイル一つですべてを管理しようとすると、TypeScriptは「どこからどこまでが関係しているのか」を毎回ぜんぶ調べ直さないといけません。これがビルド（変換）が遅くなる原因です。

「Project References」は、この巨大な設計図を「お店ごと」「エリアごと」に小分けにする手法です。

おもちゃ屋さんはおもちゃ屋さんの設計図（`tsconfig.json`）
本屋さんは本屋さんの設計図（`tsconfig.json`）

これらを別々に管理し、最後に必要な時だけ「おもちゃ屋さんと本屋さんをつなぐ」というイメージです。

—

2. 魔法のキーワード：`composite` と `references`

Project Referencesを使うには、たった二つの合言葉を覚えるだけです。

1. `composite: true`: 「このプロジェクトは、大きな全体の一部として振る舞いますよ」という宣言。
2. `references`: 「僕はこのプロジェクトとあのプロジェクトを使っているよ」という依存関係の宣言。

これだけで、TypeScriptは「変更があった場所だけ」を賢くビルドしてくれるようになります。

具体的な設定例を見てみよう

例えば、「共通機能（utils）」を、「メイン機能（app）」が使っているというシンプルな構成で考えてみましょう。

共通機能側の設定 (`packages/utils/tsconfig.json`)

{
“compilerOptions”: {
“composite”: true, // これが大事！「私は部品です」というサイン
“declaration”: true, // 型定義ファイル(.d.ts)を生成して、外から使えるようにする
“outDir”: “dist” // 変換されたファイルの置き場所
}
}

メイン機能側の設定 (`packages/app/tsconfig.json`)

{
“compilerOptions”: {
“composite”: true
},
“references”: [
// 「僕（app）は utils に依存しているよ」と教えてあげる
{ “path”: “../utils” }
]
}

たったこれだけです。これにより、TypeScriptは「`utils`をいじった時だけ、`app`のチェックをすればいいんだな」と理解してくれるのです。

—

3. なぜこれが現場で愛されるのか？

この方法の素晴らしい点は、「壊していい場所」と「壊してはいけない場所」が明確になることです。

初心者のうちは、全てのファイルを一つのフォルダに入れてしまいがちですが、そうすると「ちょっと修正したつもりが、全く関係ない場所でエラーが起きた！」という事故が頻発します。

Project Referencesを使うと、物理的にフォルダが分かれるため、

「ここは共通ライブラリだから、不用意に書き換えないでおこう」
「ここはメインの機能だから、型をしっかり守ろう」

という意識が自然と芽生えます。これはコードを書く上で非常に大切な「境界線」の感覚を養ってくれるんです。

—

4. 最初の一歩を踏み出すあなたへ

「設定ファイルが二つに増えるの？面倒くさそう…」と思うかもしれません。大丈夫です。最初は難しく感じるのが普通です。

まずは、「プロジェクトが大きくなってきたな」と感じたとき、一番切り出しやすい「共通関数」や「UIコンポーネント」を一つだけ別のディレクトリに出してみることから始めてみてください。

全部を一度に完璧にする必要なんてありません。現場のアーキテクトだって、最初は小さな一歩から積み重ねています。

TypeScriptは、あなたの開発体験を良くするためのツールです。複雑な設定に振り回されるのではなく、自分を助けてくれる仕組みを少しずつ取り入れていく。その姿勢があれば、あなたはきっと素晴らしいエンジニアになれますよ。

もし途中でエラーが出たり、設定がうまくいかなくても落ち込まないでください。それは「もっと学びたい」というあなたの情熱が、一歩先へ進もうとしている証拠ですから。

何かあれば、いつでもまた聞きに来てくださいね。あなたのコードが、今日も健やかでありますように！