TypeScriptプロジェクト参照の解説
複数パッケージのビルドにcompositeとreferencesの設定を使います。
「TypeScriptプロジェクト参照の解説」はCoddyKit上の無料TypeScript Academyレッスンです。 これはレッスン1/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはTypeScript Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 TypeScript Academyコースには全4レッスンが含まれています。
プロジェクト参照とは
プロジェクト参照を使用すると、TypeScript のコードベースを、相互の依存関係を宣言する複数の tsconfig プロジェクトに分割できます。これにより、増分ビルドと分離されたビルドが可能になります。
// tsconfig.json (root)
{
"references": [
{ "path": "./packages/core" },
{ "path": "./packages/ui" }
]
}コンポジットプロジェクト
参照される各プロジェクトでは、tsconfig に "composite": true を設定する必要があります。これにより、宣言ファイルのキャッシュと依存関係の追跡が有効になります。
// packages/core/tsconfig.json
{
"compilerOptions": {
"composite": true,
"declaration": true,
"outDir": "./dist"
}
}tsc --build によるビルド
ルートから tsc --build（または tsc -b）を実行すると、参照されているすべてのプロジェクトが依存関係の順序に従ってビルドされます。
# Build all projects
tsc --build
# Build and watch
tsc --build --watch
# Clean build outputs
tsc --build --clean増分リビルド
初回のビルド後、tsc --build はソースファイルまたは依存関係が変更されたプロジェクトだけを再コンパイルするため、大規模なリポジトリでのビルドを大幅に高速化できます。
# Only changed packages are rebuilt
tsc --build
# Output: 2/5 projects up to date — skipping宣言ファイルの利用
参照先のプロジェクトは、依存関係をソースの TypeScript ファイルから再解析するのではなく、dist/ に生成された依存関係の .d.ts ファイルを介して利用します。
// packages/ui imports from packages/core
import { Button } from "@myapp/core"; // resolved via dist/index.d.tsパス設定
ルートの tsconfig に paths を設定するか、package.json の exports を使用して、開発中に TypeScript がパッケージのインポートを正しく解決できるようにします。
{
"compilerOptions": {
"paths": {
"@myapp/core": ["./packages/core/src/index.ts"]
}
}
}ビルド順序の維持
TypeScript は参照グラフからビルド順序を自動的に決定します。循環参照は検出され、エラーとして報告されます。
// Circular reference error example:
// packages/core references packages/ui
// packages/ui references packages/core
// Error: Circular project referenceoutDir と rootDir
各コンポジットプロジェクトでは、出力レイアウトを制御し、パッケージ境界を越えたファイルの漏出を防ぐために、outDir と rootDir を設定します。
{
"compilerOptions": {
"rootDir": "./src",
"outDir": "./dist"
}
}ビルドツールとの統合
Turborepo、Nx、Lerna はプロジェクト参照と連携し、依存関係グラフに基づいてビルドをキャッシュおよび並列化します。
// turbo.json — declare TypeScript build as a pipeline step
{
"pipeline": {
"build": { "dependsOn": ["^build"], "outputs": ["dist/**"] }
}
}複数プロジェクトの監視
tsc --build --watch は参照されているすべてのプロジェクトを監視し、変更のたびに増分再コンパイルを行うため、モノレポでほぼ即時のフィードバックが得られます。
# Terminal: tsc --build --watch
# [9:00:01 AM] Found 0 errors. Watching for file changes.まとめ: プロジェクト参照
プロジェクト参照を使用すると、TypeScript を分離されキャッシュ可能なビルド単位に分割できます。composite: true を設定し、references を宣言して、tsc --build を使用することで、モノレポで高速かつ正確な増分ビルドを実現します。
確認問題
プロジェクトが別のプロジェクトから参照されるために必要な tsconfig のオプションは何ですか。
学んだこと
TypeScript のプロジェクト参照により、モノレポで高速かつ分離されたビルドを実現できます。composite: true を設定し、references で依存関係を宣言して、tsc --build で増分コンパイルを行います。
よくある質問
「TypeScriptプロジェクト参照の解説」レッスンは無料ですか？
はい。「TypeScriptプロジェクト参照の解説」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、TypeScript Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 TypeScript Academyコースには全4レッスンが含まれています。
「TypeScriptプロジェクト参照の解説」で何を学びますか？
複数パッケージのビルドにcompositeとreferencesの設定を使います。 ブラウザで直接実行するハンズオンコードでTypeScript Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
TypeScript Academyを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのTypeScript Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン1/4です。
「TypeScriptプロジェクト参照の解説」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このTypeScript Academyレッスンでコードを書いて実行できますか？
はい。すべてのTypeScript Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。
このコースのすべてのレッスン
- TypeScriptプロジェクト参照の解説
- TypeScriptでのpnpm Workspaces
- 共有型パッケージの戦略
- MonorepoのIncremental BuildとCache