Migrer une application Angular du constructeur Webpack vers @angular/build

Pendant des années, les projets Angular ont été construits à l’aide de Webpack via @angular-devkit/build-angular. Par défaut, l’outil CLI utilise désormais le générateur application basé sur esbuild provenant de @angular/build, et les générateurs Webpack sont en voie d’être abandonnés : selon les notes de version d’Angular 22 mentionnées au moment de la rédaction, le générateur basé sur Webpack est officiellement déprécié. Les étapes ci-dessous montrent comment transférer une application existante vers le nouveau générateur, quels changements apporter dans angular.json, quoi faire concernant les chargeurs Webpack personnalisés, et comment préparer la configuration TypeScript pour le compilateur natif Go.

Pourquoi ce changement est important maintenant

Outre la dépréciation, il y a une motivation liée aux performances. TypeScript 7.0, une version du compilateur portée sur Go sous le nom de TSGo ou Project Corsa, était à l’étape de candidat à la sortie au moment où ce texte a été rédigé, et il est présenté comme pouvant être jusqu’à 10 fois plus rapide que le compilateur basé sur JavaScript. Le plan stratégique d’Angular vise à s’appuyer sur ce compilateur, et les investissements en outils se portent sur les pipelines esbuild et Vite plutôt que sur Webpack. Les projets utilisant Webpack manqueront de ces avantages. Considérez ces délais comme sensibles et consultez les annonces actuelles.

Le nouveau générateur simplifie également la structure cible. La configuration Webpack nécessitait des générateurs distincts pour le paquet destiné au navigateur, le paquet serveur et le pré-rendering ; le générateur application produit tous ces éléments à partir d’une seule cible.

Étape 1 : remplacer le générateur dans angular.json

Ouvrez angular.json, trouvez la cible build de votre projet, et localisez l’outil de construction pour navigateurs anciens :

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

Remplacez le nom de cet outil par l’outil de construction d’applications unifié, en conservant pour l’instant l’objet des options :

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

Les versions récentes de la CLI proposent également une migration automatique via ng update qui effectue ces modifications ainsi que d’autres changements d’options ; consultez la documentation d’Angular pour obtenir la commande exacte adaptée à votre version, puis examinez le rapport de différences qu’elle génère.

Étape 2 : ajuster les options de construction

L’outil application vérifie ses options de manière plus stricte, ce qui nécessite d’attirer l’attention sur plusieurs entrées dans build.options.

• Rénommez main en browser. Le point d’entrée du client est désormais configuré avec l’option browser ; main n’est plus accepté.
• Décidez du format de sortie. Avec une chaîne simple telle que "outputPath": "dist/app", le générateur crée les sous-dossiers browser et server à l’intérieur. Les scripts de déploiement qui s’attendent à trouver des fichiers directement dans dist/app ne fonctionneront plus. Pour conserver une sortie client plate, utilisez la forme objet et mettez browser à une chaîne vide :

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

• Intégrer le SSR dans le même cible. Si l’application utilise le rendu du côté serveur, supprimez la cible architecturale séparée server et déplacez le point d’entrée serveur dans les options du constructeur d’application, ce qui permet un pré-rendu là où c’est nécessaire :

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

Puis exécutez une compilation en production et comparez le résultat avec ce que votre serveur ou votre CDN attend.

Étape 3 : remplacer les chargeurs Webpack personnalisés

Les projets qui étendent la compilation avec @angular-builders/custom-webpack sont les plus touchés : tout chargeur personnalisé, comme les importations d’SVG bruts ou un transformateur Markdown, cesse de fonctionner dès que Webpack quitte la chaîne. Il existe deux solutions possibles :

• Les ressources telles que les SVG : elles reposent sur la configuration assets intégrée d’Angular ou sont référencées depuis le CSS plutôt que d’être importées via un chargeur.

Transformations personnalisées : réimplémentez-les en tant que plugin esbuild et enregistrez-le via @angular-builders/custom-esbuild.

Énumérez d’abord ces personnalisations ; elles prennent généralement le plus de temps en termes d’ingénierie.

Étape 4 : préparer tsconfig pour TypeScript 7

Angular 22 continue de prendre en charge TypeScript 5.x et 6.x, donc TSGo n’est pas encore nécessaire. Cependant, il modifie les paramètres par défaut qui peuvent perturber la vérification des types. Le plus visible est types : il vaut par défaut une liste vide, ce qui signifie que les déclarations globales provenant de packages tels que @types/node ou @types/jest ne sont plus détectées automatiquement. Les variables globales comme process, describe ou expect génèrent alors des erreurs du type « nom non trouvé ».

La solution consiste à lister explicitement les packages de types nécessaires par projet :

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

Définissez cela dans chaque tsconfig : le code d’application nécessite généralement moins de variables globales que le code de test, et l’inclusion de jest dans la configuration de l’application provoquerait le transfert des variables globales de test vers les types en production.

Liste de vérification pour la migration

• Remplacez @angular-devkit/build-angular:browser par @angular/build:application dans angular.json.
• Rénommez main en browser, choisissez un schéma pour outputPath, et intégrez les paramètres SSR dans le seul cible.
• Transférez les chargeurs Webpack personnalisés vers la configuration des assets ou les plugins esbuild.
• Supprimez @ngtools/webpack ainsi que les autres dépendances de build exclusives à Webpack de package.json une fois qu’aucun élément ne les fait référence.
• Déclarez explicitement les types ambients dans chaque tsconfig avant la version 7 de TypeScript.

Le remplacement du constructeur en lui-même ne représente qu’un petit changement de configuration ; l’effort réside plutôt dans les chargeurs personnalisés et les chemins de déploiement. Le faire maintenant élimine la dépendance à un pipeline obsolète et permet au projet de bénéficier des compilateurs plus rapides dès leur disponibilité. Pour créer un projet vierge avec l’outilchain actuel, consultez la mise en place d’un projet Angular 22 moderne.