Migrar una aplicación Angular desde el compilador Webpack al @angular/build

Durante años, los proyectos Angular se construyeron mediante Webpack a través de @angular-devkit/build-angular. Ahora, el valor predeterminado de la CLI es el generador application basado en esbuild de @angular/build, y los generadores de Webpack están siendo eliminados: según las notas de lanzamiento de Angular 22, el generador basado en Webpack está oficialmente obsoleto. Los pasos a continuación muestran cómo migrar una aplicación existente al nuevo generador, qué cambios se producen en angular.json, qué hacer con los cargadores personalizados de Webpack y cómo preparar la configuración de TypeScript para el compilador nativo Go.

Por qué es importante este cambio ahora

Más allá de la obsolescencia, existe un motivo relacionado con el rendimiento. TypeScript 7.0, una versión del compilador adaptada a Go conocida como TSGo o Project Corsa, se encontraba en la fase de candidato a lanzamiento cuando se escribió este texto y se promociona como hasta 10 veces más rápido que el compilador basado en JavaScript. La hoja de ruta de Angular apunta a desarrollar sobre ese compilador, y la inversión en herramientas se dirige hacia los pipelines esbuild y Vite en lugar de Webpack. Los proyectos que usan Webpack se perderán esas ventajas. Considere estos plazos como críticos y consulte los anuncios actuales.

El nuevo generador también simplifica la estructura de destino. La configuración de Webpack requería generadores separados para el paquete del navegador, el paquete del servidor y la pre-renderización; en cambio, el generador application produce todos ellos a partir de un único destino.

Paso 1: cambiar el generador en angular.json

Abra angular.json, encuentre el objetivo build de su proyecto y localice el generador para navegadores antiguos:

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

Sustituya el nombre del generador por el generador de aplicaciones unificado, manteniendo por ahora el objeto de opciones:

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

Las versiones recientes de la CLI también ofrecen una migración automática a través de ng update que realiza esto y los siguientes cambios en opciones; consulte la documentación de Angular para obtener el comando exacto correspondiente a su versión y luego revise la diferencia que genera.

Paso 2: ajustar las opciones de compilación

El generador application valida sus opciones de manera más estricta, por lo que varias entradas en build.options requieren atención.

• Cambie el nombre de main a browser. El punto de entrada del cliente ahora está configurado con la opción browser; main ya no se acepta.
• Elija el diseño de la salida. Con una cadena simple como "outputPath": "dist/app", el generador crea subdirectorios browser y server dentro de ella. Los scripts de despliegue que esperan archivos directamente en dist/app dejarán de funcionar. Para mantener una salida plana del cliente, utilice el formato de objeto y establezca browser en una cadena vacía:

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

• Integrar el SSR en el mismo destino. Si la aplicación utiliza renderizado del lado servidor, elimine el destino de arquitectura server separado y mueva el punto de entrada del servidor a las opciones del generador de aplicaciones, lo que permitirá realizar el prerenderizado allí según sea necesario:

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

Luego ejecute una compilación para producción y compare el resultado con lo que espera su servidor o CDN.

Paso 3: reemplazar los cargadores personalizados de Webpack

Los proyectos que amplían la compilación con @angular-builders/custom-webpack son los más afectados: cualquier cargador personalizado, como importaciones de SVG en bruto o un transformador de Markdown, deja de funcionar en el momento en que Webpack abandona la cadena. Hay dos opciones posibles:

• Recursos como los SVG: deben basarse en la configuración assets integrada de Angular o referenciarse a ellos desde CSS en lugar de importarlos mediante un cargador.

Transformaciones personalizadas: reimplementelas como un plugin de esbuild y regístralo a través de @angular-builders/custom-esbuild.

Primero enumere estas personalizaciones; suelen requerir la mayor cantidad de tiempo de desarrollo.

Paso 4: preparar tsconfig para TypeScript 7

Angular 22 sigue siendo compatible con TypeScript 5.x y 6.x, por lo que TSGo aún no es necesario. Sin embargo, cambia los valores predeterminados que pueden afectar la verificación de tipos. El más evidente es types: su valor por defecto es un array vacío, por lo que las declaraciones globales ambientales de paquetes como @types/node o @types/jest ya no se detectan automáticamente. Por eso, variables globales como process, describe o expect generan errores de tipo “no se puede encontrar el nombre”.

La solución es listar explícitamente los paquetes de tipos ambientales que cada proyecto necesita:

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

Establezca esto en tsconfig: el código de aplicación generalmente necesita menos variables globales que el código de pruebas, y incluir jest en la configuración de la aplicación haría que las variables globales de las pruebas se filtraran en los tipos de producción.

Lista de verificación para la migración

• Sustituya @angular-devkit/build-angular:browser por @angular/build:application en angular.json.
• Cambie el nombre de main a browser, elija un diseño para outputPath y combine las configuraciones de SSR en el único destino.
• Transfiera los cargadores personalizados de Webpack a la configuración de assets o a plugins de esbuild.
• Elimine @ngtools/webpack y otras dependencias de compilación exclusivas de Webpack de package.json una vez que ya no haya referencias a ellas.
• Declarar explícitamente los types ambientales en cada tsconfig antes de TypeScript 7.

El cambio en sí mismo de constructor es una pequeña modificación de configuración; el esfuerzo real radica en los cargadores personalizados y las rutas de despliegue. Hacerlo ahora elimina la dependencia de un pipeline obsoleto y posiciona al proyecto para beneficiarse de compiladores más rápidos a medida que salgan al mercado. Para configurar un proyecto nuevo con la cadena de herramientas actual, consulte configurar un proyecto moderno de Angular 22.

Lecturas relacionadas

• De carpeta vacía a aplicación en ejecución: Configurando un proyecto moderno de Angular 22 — Instale Node.js y la CLI de Angular, cree una aplicación de Angular 22 con ng new, comprenda la estructura de archivos standalone y ejecútela localmente con reconstrucciones en tiempo real.

Profiling a Slow Webpack Monorepo Build Before Reaching for a New Bundler — Cómo el perfilado de una construcción de microfrontend con Webpack que duraba 20 minutos llevó al descubrimiento de Terser, Babel, las instalaciones y el caché de Docker, y qué soluciones la redujeron a unos dos minutos.

Angular CLI Beyond ng serve: Generators, Targets, Cache and Build Stats — Conozca las opciones de Angular CLI que eliminan tareas rutinarias: flags de generador, ayuda integrada, comandos por proyecto, objetivos de ng run, limpieza de caché y estadísticas de construcción.