GitHub ActionsでTypeScriptモノレポを高速化する
最終更新
TypeScriptモノレポのCIでは、通常、インストールやテストは最も時間のかかる部分ではありません。遅いのは型チェックとリンティングです。ジョブごとに新しいマシンで起動し、すべてのファイルを毎回チェックし直すためです。これらを高速化するには、コンパイラのインクリメンタルな状態を実行間で保持し、git checkoutの後でも機能するLintキャッシュを使い、チェックを1本の長いチェーンではなく並列ジョブとして実行します。
このガイドでは、これら3つの方法を動作するYAMLとともに解説します。変更されたパッケージだけを実行する方法は繰り返し説明しません。それについてはpnpmワークスペースで最速のCIをご覧ください。全般的なアプローチについては、GitHub Actionsを高速化する方法をお読みください。
遅いチェックを特定する
何かを変更する前に、各チェックの時間を個別に計測してください。ワークフローでは、それぞれにステップ名を付け、実行サマリーでステップの所要時間を確認します。
- name: typecheck
run: pnpm -r --workspace-concurrency=4 run typecheck
- name: lint
run: pnpm -r --workspace-concurrency=4 run lint
- name: test
run: pnpm -r --workspace-concurrency=4 run test
3つのうちいずれかがジョブの半分以上を占めている場合は、まずそれを修正してください。以下のセクションは、効果が大きい順に、型チェック、Lint、ジョブ構成の順で説明します。
型チェック: インクリメンタルビルド
tsc --noEmitは型をチェックしますが、何も出力しません。incrementalを有効にすると、TypeScriptは.tsbuildinfoファイルも書き出します。このファイルには各ファイルについて得られた情報が記録されるため、次回の実行では変更されたファイルと、それに依存するファイルだけを再チェックします。tsconfig.jsonで次のように設定します。
{
"compilerOptions": {
"noEmit": true,
"incremental": true,
"tsBuildInfoFile": "node_modules/.cache/tsc/web.tsbuildinfo",
"skipLibCheck": true
}
}
tsBuildInfoFileは状態を任意のパスに置くので、何をキャッシュすべきかが明確になります。パッケージごとに1つのファイルを使用してください。2つのプロジェクトが同じファイルに書き込んではいけないためです。skipLibCheckは.d.tsファイルの型チェックを省略します。TypeScriptのドキュメントでは、型システムの正確さを一部犠牲にして時間を節約する設定と説明されています。自分のコードは引き続きチェックされます。ほとんどのCI環境では、このトレードオフは受け入れられています。
次に、そのフォルダをキャッシュアクションで復元・保存します。
- uses: actions/cache@v6
with:
path: node_modules/.cache/tsc
key: tsc-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
restore-keys: |
tsc-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
tsc-${{ runner.os }}-
- run: pnpm -r run typecheck
キーの末尾にコミットSHAが付くため、実行のたびに新しいコピーが保存されます。restore-keysは、直前に保存された古いコピーのうち最新のものを読み込みます。GitHubでは、実行は自身のブランチ、プルリクエストのベースブランチ、またはデフォルトブランチで保存されたキャッシュしか復元できないため、プルリクエストはmainが保存した内容から開始します。これは望ましいキャッシュの動きです。PRは変更された部分だけを再チェックすればよくなります。
新しいチェックアウトではすべてのファイルの更新時刻が新しくなりますが、このキャッシュは無効になりません。TypeScript 5.9.3で確認したところ、プロジェクトをコピー(新しいタイムスタンプ)し、内容を変えずにファイルに触れた後でも、tsc --extendedDiagnosticsはコールドランより少ない型のチェックしか報告しませんでした。TypeScriptは時刻ではなくファイルの内容を比較するからです。保存された状態がファイルと一致しない場合、TypeScriptはそれらを再チェックします。そのため古いキャッシュは遅くなることはあっても、誤った結果になることはありません。疑わしい場合は、キャッシュを削除して再実行してください。
プロジェクト参照
互いにimportし合うパッケージを持つモノレポでは、プロジェクト参照を使えます。各パッケージでcomposite: trueを設定し、ルートでビルド対象のパッケージを列挙します。
{
"files": [],
"references": [
{ "path": "packages/ui" },
{ "path": "packages/api-client" },
{ "path": "apps/web" }
]
}
tsc --build
tsc --build(または-b)は、依存関係の順に各プロジェクトをビルドし、最新のプロジェクトはスキップします。CIで頼る前に知っておくべき点が2つあります。
- ビルドモードでは参照される各パッケージについて
.d.tsを出力するため、次のパッケージはソース全体ではなく小さな宣言ファイルに対してチェックできます。大規模なグラフでは、この仕組みによって時間が短縮されます。 - ビルドモードは、新しいチェックアウトをまたいでプロジェクトをスキップできる場合があります。その最初の判定はタイムスタンプで行われ、チェックアウトによってソースが復元された出力より新しくなるためです。TypeScript 5.9.3と
tsc --build --verboseで、まさにこの状況を試しました。内容が変わっていない場合はup to date but needs to update timestamps of output files that are older than input filesと報告され、何もリビルドされませんでした。packages/libの1つのファイルを編集すると、そのプロジェクトをリビルドし、それに依存するapps/webもリビルドしましたが、それ以外は何もリビルドされませんでした。キャッシュを復元した後、ランナーで一度tsc --build --verboseを実行してください。ログには、各プロジェクトがスキップされたかリビルドされたか、その理由が示されます。 - CIでこれを利用するには、各プロジェクトの出力フォルダを
.tsbuildinfoファイルとともにキャッシュします。tsBuildInfoFileを出力フォルダ内のパス(例:dist/.tsbuildinfo)に設定すれば、1つのパスで両方をカバーできます。
- uses: actions/cache@v6
with:
path: |
packages/*/dist
apps/*/dist
key: tsb-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
restore-keys: |
tsb-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
流行っているからという理由だけでプロジェクト参照を有効にしないでください。パッケージが2つか3つのリポジトリではほとんど効果がありません。パッケージが多く、importグラフが深いリポジトリでは大きな効果があります。
Lint: checkoutをまたいで機能するキャッシュ
ESLintはファイルごとに結果を保存し、変更のないファイルをスキップできます。デフォルトのmetadata戦略では、ファイルが変更されていないかどうかを、更新時刻などのファイルメタデータで判断します。新しいチェックアウトではすべてのファイルの時刻が新しくなるため、デフォルトのキャッシュは毎回ミスする可能性があります。ESLintとPrettierはどちらも、代わりにファイルの内容を比較するcontent戦略を備えています。
eslint . --cache --cache-location node_modules/.cache/eslint/web.cache --cache-strategy content
Prettierも同じオプションを受け付けます。
prettier --check . --cache --cache-location node_modules/.cache/prettier/.prettier-cache --cache-strategy content
これらのフォルダも、TypeScriptの状態と同じ方法でキャッシュしてください。
- uses: actions/cache@v6
with:
path: |
node_modules/.cache/eslint
node_modules/.cache/prettier
key: lint-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', '**/eslint.config.*', '**/.prettierrc*') }}-${{ github.sha }}
restore-keys: |
lint-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', '**/eslint.config.*', '**/.prettierrc*') }}-
キーにはロックファイルと設定ファイルを含めます。新しいルールやプラグインのバージョンによって古い結果を無効にする必要があるためです。
型情報を使うルールはコストが高い
型情報を必要とするルール(@typescript-eslint のルール、例えば no-floating-promises)では、ESLint が TypeScript プログラムを構築します。これは構文のみのルールと比べてはるかに遅くなります。typescript-eslint のドキュメントでは、型付きのリンティングは型なしのリンティングより遅いと説明されています。現在のバージョンでは、project のパスを手動で列挙するのではなく、projectService オプションでこれを設定する方法が推奨されています。オプション:
- 型を考慮したルールは、それが必要なフォルダにだけ有効にします。
- 型を考慮したチェックを独立したジョブとして実行し、高速なLintの結果が先に返ってくるようにします。
- 特定のルールに一方しか必要ない場合は、すべてのファイルに対して完全な
tscと型を考慮したESLintの両方を実行しないでください。
チェックを並列ジョブで実行する
typecheck、lint、test を1つのジョブで順に実行すると、3つの合計時間がかかります。ジョブを3つに分けると、最も長いジョブの時間に、各ジョブのインストール時間を加えたものになります:
name: CI
on:
push:
branches: [main]
pull_request:
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
jobs:
typecheck:
runs-on: [self-hosted, Linux, compiler-ci] # or ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v6
- uses: actions/setup-node@v7
with:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- uses: actions/cache@v6
with:
path: node_modules/.cache/tsc
key: tsc-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
restore-keys: tsc-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
- run: pnpm -r run typecheck
lint:
runs-on: [self-hosted, Linux, compiler-ci]
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v6
- uses: actions/setup-node@v7
with:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- uses: actions/cache@v6
with:
path: node_modules/.cache/eslint
key: lint-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
restore-keys: lint-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
- run: pnpm -r run lint
test:
runs-on: [self-hosted, Linux, compiler-ci]
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v6
- uses: actions/setup-node@v7
with:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm -r run test
cancel-in-progress を設定すると、同じブランチに新しくプッシュしたときに古い実行が停止され、時間も節約できます。詳しくはGitHub Actions の料金を抑える方法をご覧ください。各ジョブでインストールが行われるため、pnpm のストアはキャッシュしておいてください。詳細はGitHub Actions で pnpm をキャッシュする方法に記載しています。ジョブを分割する効果が出るのは、インストールがチェック処理に比べて短い場合です。インストールに最も時間がかかる場合は、1つのジョブにまとめたほうが速くなります。
ブランチ保護で、ジョブ名を指定してチェックを必須に設定してください。これにより、遅いジョブが誤ってスキップされることを防げます。
CPU コア数を増やす効果
1つのプロジェクトに対する tsc は主にシングルスレッドで動作しますが、モノレポには多くのプロジェクトがあります。pnpm -r はそれらを並列に実行し、パッケージ全体の ESLint やテストランナーも同様です。コア数が増えた場合は、--workspace-concurrency をそれに合わせて設定してください。たとえば8コアのマシンなら 8 です。メモリも重要です。型情報を使う大規模な ESLint の実行では数GBが必要になることがあり、2 vCPU のホステッドランナーの合計メモリは 7 GB です。
リポジトリでどれだけ効果があるかを確認するには、runs-on: [self-hosted, Linux, compiler-ci] の1行を変更して実行時間を比較するか、現在のジョブと並行してコピーを実行する比較モードをお使いください。料金、比較、ベンチマークもご覧ください。パイプライン全体については、CI が遅い場合のハブから始めてください。
よくある質問
.tsbuildinfo ファイルをキャッシュすべきですか?
型チェックがジョブ全体に占める割合が大きい場合は、キャッシュすることをお勧めします。tsBuildInfoFile に既知のパスを設定し、そのフォルダーをキャッシュしてください。キャッシュが古くなっても TypeScript はより多くのファイルをチェックするだけなので、安全です。
CI でキャッシュを使うと tsc --build は動作しますか?
はい。TypeScript 5.9.3 では、新しいチェックアウトによってソースが出力より新しくなっても、内容が変わっていなければ復元されたキャッシュが使われました。お使いのバージョンでどのプロジェクトがスキップされるかを確認するには、キャッシュを復元した後に tsc --build --verbose を一度実行してください。
skipLibCheck は安全ですか?
宣言ファイルのチェックをスキップするため、依存関係の型定義内のエラーは報告されません。ご自身のコード内のエラーは引き続き報告されます。多くのチームがこれを有効にしています。
CI で ESLint のキャッシュが一度もヒットしないのはなぜですか?
デフォルトの方式(metadata)は、更新時刻などのファイルのメタデータから変更を検出します。新しいチェックアウトではそれらがすべて変わるためです。--cache-strategy content を使い、キャッシュファイルを保存しているフォルダーをキャッシュしてください。
typecheck、lint、test は別々のジョブにすべきですか?
それぞれに数分かかる場合は、分けることをお勧めします。各ジョブの大半がインストールである場合は、分けるべきではありません。インストールに3回分の時間がかかってしまうためです。
関連記事
- GitHub ActionsでモノレポのPlaywrightを高速化するGitHub Actions で Node モノレポの Playwright E2E テストを高速化: アプリを一度だけビルドし、Web アプリに変更がないときは E2E をスキップし、シャーディングとレポートのマージを行います。
- READMEにCIの速度バッジを追加するREADME のバッジで CI の速さを表示しましょう。リポジトリの GitHub Actions 実行時間の中央値が自動で更新されます。公開リポジトリは無料です。
- GitHub ActionsでBazelモノレポを最速でCIするGitHub Actions での高速な Bazel CI。影響を受けるビルドのためのターゲット判定、リモートキャッシュのフラグ、PR からの読み取り専用アップロード、シャーディング、完全なワークフローを紹介します。
- GitHub ActionsでNxモノレポを最速でCIするGitHub Actions で Nx の CI を高速化。nx-set-shas を使った nx affected、Nx リモートキャッシュ、タスク分散、fetch-depth、完全なワークフローを紹介します。