Migration einer Angular-Anwendung vom Webpack Builder zu @angular/build

Jahrelang wurden Angular-Projekte mithilfe von Webpack über @angular-devkit/build-angular erstellt. Der Standard der CLI ist nun der auf esbuild basierende application-Builder aus @angular/build, wobei die Webpack-Builder allmählich veraltet werden: Laut den Veröffentlichungshinweisen zu Angular 22, wie sie zum Zeitpunkt der Erstellung veröffentlicht wurden, ist der auf Webpack basierende Builder offiziell veraltet. Die folgenden Schritte zeigen, wie man eine bestehende Anwendung auf den neuen Builder überträgt, welche Änderungen in angular.json erforderlich sind, was man mit benutzerdefinierten Webpack-Loadern machen sollte und wie man die TypeScript-Konfiguration für den nativen Go-Compiler vorbereitet.

Warum dieser Wechsel jetzt wichtig ist

Neben der Veraltungsstrategie gibt es auch einen Leistungsaspekt. TypeScript 7.0, eine Portierung des Compilers in Go unter dem Namen TSGo oder Project Corsa, befand sich zum Zeitpunkt der Erstellung in der Release-Candidate-Phase und wird als bis zu 10 Mal schneller als der auf JavaScript basierende Compiler beworben. Angulos Entwicklungsplan zielt darauf ab, auf diesem Compiler aufzubauen, und die Investitionen in Tools fließen in die esbuild- sowie Vite-Pipelines statt in Webpack. Webpack-Projekte werden diese Vorteile nicht erhalten. Betrachten Sie die Zeitpläne als zeitkritisch und prüfen Sie aktuelle Ankündigungen.

Der neue Builder vereinfacht außerdem die Zielstruktur. Die Webpack-Einrichtung benötigte separate Builder für das Browser-Bundle, das Server-Bundle und das Vorrendern; der application-Builder erzeugt all diese Elemente aus einem einzigen Ziel heraus.

Schritt 1: Den Builder in angular.json austauschen

Öffnen Sie angular.json, finden Sie das build-Ziel Ihres Projekts und identifizieren Sie den herkömmlichen Browser-Builder:

// DELETE the legacy Webpack builder
"build": {
  "builder": "@angular-devkit/build-angular:browser",
  "options": { ... }
}

Ersetzen Sie den Namen des Builders durch den einheitlichen Anwendungs-Builder und behalten Sie vorerst das Options-Objekt bei:

// MIGRATE to the unified esbuild application builder
"build": {
  "builder": "@angular/build:application",
  "options": { ... }
}

Neueere CLI-Versionen bieten außerdem eine automatisierte Migration über ng update an, die diese sowie weitere Optionen ändert; prüfen Sie in der Angular-Dokumentation den genauen Befehl für Ihre Version und überprüfen Sie anschließend die erzeugte Diff-Datei.

Schritt 2: Anpassung der Build-Optionen

Der application-Builder überprüft seine Optionen strenger, weshalb mehrere Einträge in build.options Aufmerksamkeit erfordern.

• Ändern Sie den Namen von main in browser. Der Einstiegspunkt für den Client ist nun mit der Option browser konfiguriert; main wird nicht mehr akzeptiert.
• Entscheiden Sie sich für das Ausgabemuster. Mit einem einfachen String wie "outputPath": "dist/app" erstellt der Builder die Unterordner browser und server darin. Deployment-Skripte, die mit Dateien direkt in dist/app rechnen, werden nicht funktionieren. Um eine flache Klientenausgabe beizubehalten, verwenden Sie die Objektform und setzen browser auf einen leeren String:

"outputPath": {   "base": "dist/app",   "browser": "" }

• Fügen Sie das SSR zum selben Ziel hinzu. Wenn die Anwendung Server-Side Rendering verwendet, entfernen Sie das separate server-Architekturziel und verschieben Sie den Server-Eintrittspunkt in die Optionen des Anwendungs-Builders, um bei Bedarf dort eine Vorrenderung zu ermöglichen:

"server": "src/main.server.ts", "prerender": true

Führen Sie anschließend einen Produktions-Build aus und vergleichen Sie die Ausgabe mit dem, was Ihr Server oder CDN erwartet.

Schritt 3: Ersetzen Sie benutzerdefinierte Webpack-Loader

Projekte, die den Build mit @angular-builders/custom-webpack erweitern, sind am stärksten betroffen: Jeder benutzerdefinierte Loader, wie z. B. Roh-SVG-Importe oder ein Markdown-Transformer, funktioniert nicht mehr, sobald Webpack die Kette verlässt. Es gibt zwei mögliche Lösungswege:

• Ressourcen wie SVGs: Sie verlassen sich auf Angular’s eingebaute assets-Konfiguration oder referenzieren sie aus CSS, anstatt sie über einen Loader zu importieren.

Customisierte Transformationen: Implementieren Sie sie als esbuild-Plugin und registrieren Sie es über @angular-builders/custom-esbuild.

Listen Sie zunächst diese Anpassungen auf; sie erfordern in der Regel die meisten Entwicklungszeit.

Schritt 4: tsconfig für TypeScript 7 vorbereiten

Angular 22 unterstützt weiterhin TypeScript 5.x und 6.x, daher ist TSGo noch nicht erforderlich. Es ändert jedoch Standardwerte, die die Typüberprüfung stören können. Der auffälligste ist types: Standardmäßig handelt es sich dabei um ein leeres Array, wodurch globale Deklarationen aus Paketen wie @types/node oder @types/jest nicht mehr automatisch erkannt werden. Globale Variablen wie process, describe oder expect verursachen dann Fehler vom Typ „Name nicht gefunden“.

Die Lösung besteht darin, die für jedes Projekt benötigten ambienten Typpakete ausdrücklich aufzulisten:

// tsconfig.json
"compilerOptions": {
  // You must now explicitly declare ambient types for TSGo compatibility
  "types": ["node", "jest"]
}

Stellen Sie dies in der tsconfig ein: Anwendungscode benötigt in der Regel weniger Globale als Testcode, und die Aufnahme von jest in die App-Konfiguration würde Test-Globale in die Produktionsversionen einsickern lassen.

Migrations-Checkliste

• Ersetzen Sie @angular-devkit/build-angular:browser durch @angular/build:application in angular.json.
• Ändern Sie den Namen von main in browser, wählen Sie eine outputPath-Struktur aus und integrieren Sie die SSR-Einstellungen in das einzige Ziel.
• Portieren Sie benutzerdefinierte Webpack-Loader in die Asset-Konfiguration oder esbuild-Plugins.
• Nehmen Sie @ngtools/webpack sowie andere nur für Webpack vorgesehene Build-Abhängigkeiten aus package.json entfernen, sobald nichts mehr auf sie verweist.
• Deklarieren Sie Ambient-Types explizit in jeder tsconfig vor TypeScript 7.

Der Austausch des Compilers selbst ist eine geringfügige Konfigurationsänderung; die eigentliche Herausforderung liegt in den benutzerdefinierten Ladeverfahren sowie den Bereitstellungspfaden. Wenn man dies jetzt durchführt, entfällt die Abhängigkeit von einem veralteten Pipeline-System und das Projekt kann von schnelleren Compilern profitieren, sobald diese verfügbar sind. Zur Einrichtung eines neuen Projekts mit der aktuellen Toolchain siehe die Einrichtung eines modernen Angular 22-Projekts.