TypeScript プロジェクト参照 References

プロジェクト参照は、TypeScriptが提供する大規模プロジェクトを整理する機能で、TypeScriptプロジェクトをより小さな部分に分割できます。

インクリメンタルビルド、より良いコード整理、そしてより高速なコンパイルを実現できます。


SVG図: プロジェクト参照の動作原理 背景 タイトル プロジェクト参照 References の原理 メインプロジェクト メインプロジェクト (app) package.json tsconfig.json references: [...] 矢印 参照先プロジェクト1 コンポーネントライブラリ (ui) Button, Modal, Input 参照先プロジェクト2 ツールライブラリ (utils) formatDate, request 参照先プロジェクト3 型定義 (types) User, API Response 矢印マーカー

なぜプロジェクト参照が必要なのか

プロジェクトが成長するにつれて、単一の tsconfig.json ではコンパイル速度が遅くなります。

プロジェクト参照を使用すると、プロジェクトを独立したサブプロジェクトに分割でき、各サブプロジェクトを個別にコンパイルできます。

これによりコンパイル速度が向上するだけでなく、より良いコード整理方法も提供されます。

概念:プロジェクト参照を使用すると、あるTypeScriptプロジェクトが他のプロジェクトを参照でき、インクリメンタルコンパイルとより良いコード整理を実現できます。


参照プロジェクトの作成

まず、参照されるサブプロジェクトを作成します。

packages/utils/tsconfig.json

{
    // 基本設定を継承
    "extends": "../../tsconfig.base.json",

    // コンパイラオプション
    "compilerOptions": {
        // 出力ディレクトリ
        "outDir": "./dist",

        // 宣言ファイルディレクトリ
        "declarationDir": "./dist/types",

        // 宣言ファイルを生成
        "declaration": true,

        // sourcemap を生成
        "sourceMap": true,

        // ライブラリかどうか
        "composite": true
    },

    // 含まれるファイル
    "include": ["src/**/*"],

    // 除外されるファイル
    "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

composite:true に設定してプロジェクト参照機能を有効にします。これは参照されるプロジェクトが必ず設定する必要があるオプションです。


メインプロジェクトの設定

メインプロジェクトの tsconfig.json で references を設定します。

tsconfig.json (メインプロジェクト)

{
    // 基本設定を継承
    "extends": "./tsconfig.base.json",

    // コンパイラオプション
    "compilerOptions": {
        // 出力ディレクトリ
        "outDir": "./dist",

        // 宣言ファイルディレクトリ
        "declarationDir": "./dist/types",

        // 宣言ファイルを生成
        "declaration": true,

        // sourcemap を生成
        "sourceMap": true
    },

    // プロジェクト参照設定
    "references": [
        // utils プロジェクトを参照
        { "path": "./packages/utils" },

        // ui プロジェクトを参照
        { "path": "./packages/ui" },

        // types プロジェクトを参照
        { "path": "./packages/types" }
    ],

    // 含まれるファイル
    "include": ["src/**/*"],

    // 依存に含まれる node_modules
    // "files": []
}

references:配列内の各オブジェクトは参照するプロジェクトのパスを指定し、path は現在のプロジェクトからの相対パスです。


型参照

コード内で参照先プロジェクトの型を使用します。

src/index.ts

// ユーティリティ関数をインポート(utils パッケージから)
import { formatDate, formatCurrency } from '@my-utils/format';

// コンポーネントをインポート(ui パッケージから)
import { Button, Modal, Input } from '@my-ui/core';

// 型をインポート(types パッケージから)
import { User, ApiResponse } from '@my-types/common';

// ユーザーデータを定義
const user: User = {
    id: 1,
    name: "Alice",
    email: "alice@example.com"
};

// 日付をフォーマット
const dateStr = formatDate(new Date(), "YYYY-MM-DD");
console.log("日付: " + dateStr);

// 通貨をフォーマット
const price = formatCurrency(999);
console.log("価格: " + price);

// ユーザーインターフェースを作成
const button = new Button({
    text: "送信",
    variant: "primary"
});

console.log("アプリの初期化に成功しました");

インポート方法:参照先プロジェクトのエクスポートは直接インポートでき、TypeScriptが自動的に型を解決します。


インクリメンタルビルド

プロジェクト参照はインクリメンタルビルドをサポートし、変更された部分のみをコンパイルします。

ビルドコマンド

# プロジェクト全体をビルド(すべての参照を含む)
npm run build

# メインプロジェクトのみをビルド(依存を再ビルドしない)
npm run build -- --build

# クリーンして再ビルド
npm run clean
npm run build

# インクリメンタルビルド(推奨)
# パッケージを変更した後、そのパッケージとそれに依存するパッケージのみを再コンパイル
npx tsc -b packages/utils
npx tsc -b packages/ui
npx tsc -b .

インクリメンタルビルド:-b (build) オプションを使用すると、TypeScriptがどのプロジェクトを再コンパイルする必要があるかを自動的に検出します。


注意事項

  • composite オプション:参照されるプロジェクトは composite: true を設定する必要があります
  • 出力ディレクトリ:各プロジェクトには独立した出力ディレクトリが必要です
  • 宣言ファイル:参照されるプロジェクトは宣言ファイルを生成する必要があります
  • ビルド順序:依存するプロジェクトを先にビルドする必要があります

ベストプラクティス:共通コードを独立したパッケージに分割し、プロジェクト参照を使用して管理することで、コンパイル効率を向上させます。


まとめ

プロジェクト参照は、TypeScriptが大規模プロジェクトを管理するための中心的な機能です。

  • references:プロジェクト参照関係の設定
  • composite:プロジェクト参照の有効化
  • インクリメンタルビルド:変更された部分のみをコンパイル
  • コード整理:独立したモジュールに分割

推奨:大規模プロジェクトでは、プロジェクト参照を使用してコードを整理し、開発効率を向上させます。

その他の拡張