Zum Inhalt springen

TypeScript-Monorepo in GitHub Actions beschleunigen

Zuletzt aktualisiert am

In einem TypeScript-Monorepo sind Installation und Tests in der CI meist nicht der langsamste Teil. Langsamer sind Typprüfung und Linting, weil jeder Job auf einer frischen Maschine startet und jede Datei erneut prüft. Um sie zu beschleunigen, behalten Sie den inkrementellen Zustand des Compilers zwischen den Läufen bei, verwenden Lint-Caches, die auch nach einem frischen git checkout funktionieren, und führen die Prüfungen als parallele Jobs aus statt als eine lange Kette.

Dieser Leitfaden behandelt diese drei Punkte mit funktionierendem YAML. Wie Sie nur die geänderten Pakete ausführen, wird hier nicht wiederholt; das finden Sie unter schnellste CI für pnpm-Workspaces. Den allgemeinen Ansatz erklärt so beschleunigen Sie GitHub Actions.

Langsame Prüfung messen

Messen Sie jede Prüfung einzeln, bevor Sie etwas ändern. Geben Sie in einem Workflow jedem Schritt einen Namen und lesen Sie die Schrittdauern in der Laufübersicht ab:

- 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

Wenn eine der drei mehr als die Hälfte des Jobs ausmacht, beheben Sie diese zuerst. Die folgenden Abschnitte halten sich an die übliche Reihenfolge nach dem Nutzen: zuerst die Typprüfung, dann das Linting, dann der Aufbau der Jobs.

Typprüfung: inkrementelle Builds

tsc --noEmit prüft die Typen und schreibt nichts. Wenn Sie incremental aktivieren, schreibt TypeScript zusätzlich eine Datei .tsbuildinfo, in der festgehalten ist, was über jede Datei bekannt ist. Ein späterer Lauf prüft dann nur noch geänderte Dateien und die Dateien, die von ihnen abhängen. In tsconfig.json:

{
  "compilerOptions": {
    "noEmit": true,
    "incremental": true,
    "tsBuildInfoFile": "node_modules/.cache/tsc/web.tsbuildinfo",
    "skipLibCheck": true
  }
}
  • tsBuildInfoFile legt den Zustand in einen Pfad Ihrer Wahl, sodass klar ist, was gecacht werden muss. Verwenden Sie pro Paket eine eigene Datei, denn zwei Projekte dürfen nicht dieselbe Datei beschreiben.
  • skipLibCheck überspringt die Typprüfung von .d.ts-Dateien. Laut TypeScript-Dokumentation spart das Zeit auf Kosten etwas geringerer Genauigkeit des Typsystems. Ihr eigener Code wird weiterhin geprüft. Die meisten CI-Setups nehmen diesen Kompromiss in Kauf.

Stellen Sie diesen Ordner anschließend mit der Cache-Action wieder her und speichern Sie ihn:

- 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

Der Schlüssel endet auf den Commit-SHA, sodass jeder Lauf eine neue Kopie speichert, und restore-keys lädt die neueste frühere Kopie. GitHub erlaubt einem Lauf nur, Caches wiederherzustellen, die vom eigenen Branch, vom Basis-Branch des Pull Requests oder vom Standard-Branch gespeichert wurden. Pull Requests starten also mit dem, was main gespeichert hat. Genau dieser Cache ist gewünscht: Ein PR prüft dann nur neu, was er geändert hat.

Ein frischer Checkout vergibt jeder Datei einen neuen Änderungszeitpunkt, das macht diesen Cache aber nicht unbrauchbar. Wir haben mit TypeScript 5.9.3 geprüft: Nach dem Kopieren eines Projekts (neue Zeitstempel) und dem Berühren der Dateien ohne inhaltliche Änderung meldete tsc --extendedDiagnostics trotzdem weniger geprüfte Typen als ein Kaltstart, weil TypeScript den Dateiinhalt vergleicht, nicht die Zeit. Passt der gespeicherte Zustand nicht zu Ihren Dateien, prüft TypeScript sie erneut. Ein veralteter Cache ist also langsamer, aber nie falsch. Vermuten Sie einen Fehler, löschen Sie ihn und starten Sie neu.

Project References

Ein Monorepo mit Paketen, die sich gegenseitig importieren, kann Project References nutzen. Jedes Paket setzt composite: true, und das Root-Projekt listet die Pakete auf, die es baut:

{
  "files": [],
  "references": [
    { "path": "packages/ui" },
    { "path": "packages/api-client" },
    { "path": "apps/web" }
  ]
}
tsc --build

tsc --build (oder -b) baut jedes Projekt in Abhängigkeitsreihenfolge und überspringt Projekte, die aktuell sind. Zwei Dinge sollten Sie wissen, bevor Sie sich darauf in der CI verlassen:

  • Der Build-Modus schreibt eine .d.ts-Ausgabe für jedes referenzierte Paket, sodass das nächste Paket gegen eine kleine Deklarationsdatei statt den vollständigen Quellcode prüfen kann. Bei großen Graphen sinkt die Zeit dadurch deutlich.
  • Der Build-Modus kann Projekte nach einem frischen Checkout überspringen. Seine erste Prüfung sind Zeitstempel, und ein Checkout macht Ihre Quellen neuer als die wiederhergestellten Ausgaben. Wir haben genau das mit TypeScript 5.9.3 und tsc --build --verbose getestet: Bei unveränderten Inhalten meldete es up to date but needs to update timestamps of output files that are older than input files und baute nichts neu. Nachdem wir eine Datei in packages/lib geändert hatten, baute es dieses Projekt neu, danach apps/web, das davon abhängt, und sonst nichts. Führen Sie tsc --build --verbose nach dem Wiederherstellen des Caches einmal auf Ihrem Runner aus; das Protokoll zeigt für jedes Projekt, ob es übersprungen oder neu gebaut wurde, und warum.
  • Um das in der CI zu nutzen, cachen Sie den Ausgabeordner jedes Projekts zusammen mit seiner .tsbuildinfo-Datei. Setzen Sie tsBuildInfoFile auf einen Pfad im Ausgabeordner (zum Beispiel dist/.tsbuildinfo), damit ein Pfad beides abdeckt:
- 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') }}-

Aktivieren Sie Project References nicht nur, weil es modern wirkt. Ein Repository mit zwei oder drei Paketen gewinnt wenig. Ein Repository mit vielen Paketen und einem tiefen Importgraphen gewinnt viel.

Linting: Caches, die einen Checkout überstehen

ESLint kann Ergebnisse pro Datei speichern und unveränderte Dateien überspringen. Die Standardstrategie metadata entscheidet anhand von Dateimetadaten wie dem Änderungszeitpunkt, ob eine Datei unverändert ist. Ein frischer Checkout vergibt jeder Datei einen neuen Zeitpunkt, deshalb kann der Standard-Cache bei jedem Lauf verfehlen. ESLint und Prettier haben beide eine Strategie content, die stattdessen den Dateiinhalt vergleicht:

eslint . --cache --cache-location node_modules/.cache/eslint/web.cache --cache-strategy content

Prettier akzeptiert dieselben Optionen:

prettier --check . --cache --cache-location node_modules/.cache/prettier/.prettier-cache --cache-strategy content

Cachen Sie diese Ordner genauso wie den TypeScript-Zustand:

- 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*') }}-

Der Schlüssel enthält das Lockfile und die Konfigurationsdateien, denn eine neue Regel- oder Plugin-Version muss alte Ergebnisse ungültig machen.

Typbasierte Lint-Regeln kosten mehr

Regeln, die Typinformationen brauchen (@typescript-eslint-Regeln wie no-floating-promises), lassen ESLint ein TypeScript-Programm aufbauen. Das ist deutlich langsamer als rein syntaxbasierte Regeln. Die Dokumentation von typescript-eslint sagt, typisiertes Linting sei langsamer als untypisiertes, und in aktuellen Versionen richten Sie es über die Option projectService ein, statt project-Pfade von Hand aufzulisten. Optionen:

  • Aktivieren Sie typbasierte Regeln nur für die Ordner, die sie brauchen.
  • Führen Sie den typbasierten Durchlauf als eigenen Job aus, damit die schnellen Lint-Ergebnisse zuerst vorliegen.
  • Führen Sie nicht bei jeder Datei sowohl ein vollständiges tsc als auch typbasiertes ESLint aus, wenn Sie für eine bestimmte Regel nur eines davon brauchen.

Prüfungen als parallele Jobs ausführen

Ein Job, der typecheck, dann lint und dann test ausführt, braucht die Summe der drei Laufzeiten. Drei Jobs brauchen nur die des längsten, plus jeweils eine Installation:

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 bricht ältere Läufe desselben Branches ab, wenn Sie erneut pushen, und spart so ebenfalls Minuten; siehe GitHub-Actions-Kosten senken. Jeder Job führt eine Installation aus, deshalb sollten Sie den pnpm-Store cachen; pnpm in GitHub Actions cachen beschreibt die Details. Die Aufteilung lohnt sich, wenn die Installation im Vergleich zu den Prüfungen kurz ist. Ist die Installation der langsame Teil, ist ein einzelner Job schneller.

Machen Sie die Prüfungen im Branch-Schutz über den Job-Namen verpflichtend, damit ein langsamer Job nicht versehentlich übersprungen wird.

Was mehr CPU-Kerne bringen

tsc läuft für ein einzelnes Projekt größtenteils single-threaded, aber ein Monorepo enthält viele Projekte, und pnpm -r führt sie parallel aus, ebenso ESLint über alle Pakete und der Test-Runner. Mit mehr Kernen sollten Sie --workspace-concurrency entsprechend setzen, zum Beispiel 8 auf einer Maschine mit 8 Kernen. Auch der Speicher ist wichtig: ein großer typbewusster ESLint-Lauf kann mehrere Gigabyte benötigen, und ein gehosteter Runner mit 2 vCPU hat insgesamt 7 GB.

Um zu sehen, was Ihr Repository gewinnt, ändern Sie eine Zeile auf runs-on: [self-hosted, Linux, compiler-ci] und vergleichen Sie die Laufzeiten, oder nutzen Sie den Vergleichsmodus, der eine Kopie Ihrer Jobs neben den aktuellen ausführt. Siehe Preise, Vergleich und unsere Benchmarks. Für den Rest der Pipeline beginnen Sie beim Hub für langsame CI.

FAQ

Sollte ich die Datei .tsbuildinfo cachen?

Ja, wenn die Typprüfung einen großen Anteil am Job ausmacht. Setzen Sie tsBuildInfoFile auf einen festen Pfad und cachen Sie diesen Ordner. Ist der Cache veraltet, prüft TypeScript einfach mehr Dateien, das ist also unbedenklich.

Funktioniert tsc --build mit einem Cache in der CI?

Ja. In TypeScript 5.9.3 wurde ein wiederhergestellter Cache verwendet, obwohl ein frischer Checkout die Quellen neuer machte als die Ausgaben, solange sich ihre Inhalte nicht geändert hatten. Führen Sie tsc --build --verbose einmal nach dem Wiederherstellen des Caches aus, um zu sehen, welche Projekte in Ihrer Version übersprungen werden.

Ist skipLibCheck sicher?

Es überspringt die Prüfung von Deklarationsdateien, daher werden Fehler in den Typen Ihrer Abhängigkeiten nicht gemeldet. Fehler in Ihrem eigenen Code werden weiterhin gemeldet. Die meisten Teams aktivieren es.

Warum trifft mein ESLint-Cache in der CI nie?

Die Standardstrategie (metadata) erkennt Änderungen anhand von Dateimetadaten wie der Änderungszeit, und ein frischer Checkout ändert alle davon. Verwenden Sie --cache-strategy content und cachen Sie den Ordner, der die Cache-Datei enthält.

Sollten typecheck, lint und test separate Jobs sein?

Wenn jeder ein paar Minuten braucht, ja. Macht die Installation den größten Teil jedes Jobs aus, nein: Sie zahlen sie dreimal.

Diesen Monorepo-Build auf compiler.dev ausführen Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen