2. Angular: arquitectura, CLI y estructura del proyecto

2.1 Qué vas a poder hacer al terminar

• Explicar en una entrevista técnica por qué Angular se reescribió por completo en 2016 y qué problemas concretos de AngularJS resolvía esa reescritura.
• Argumentar con datos, y no con preferencias, cuándo Angular es la elección correcta frente a React, Vue o Svelte, y cuándo no lo es.
• Describir el recorrido completo de una plantilla desde el fichero .html hasta las instrucciones de renderizado que ejecuta el navegador, y qué papel juegan la compilación AOT, Ivy y el tree shaking.
• Distinguir el incremental DOM de Angular del virtual DOM de React, y razonar sobre sus consecuencias en memoria y en tamaño del bundle.
• Manejar el CLI con soltura: generar cualquier artefacto, entender qué escribe cada schematic, y actualizar una versión mayor con ng update sabiendo qué hacen las migraciones automáticas.
• Leer y modificar angular.json con criterio: builders, configurations, presupuestos, reemplazos de fichero y opciones de optimización.
• Escribir un main.ts y un app.config.ts de producción, con enrutado, cliente HTTP, animaciones diferidas, inicialización de la aplicación y un ErrorHandler propio.
• Migrar mentalmente —y con la herramienta oficial— de NgModule a componentes standalone, y explicar por qué el segundo modelo es hoy el estándar.
• Diseñar la estructura de carpetas de una aplicación grande, con límites claros entre capas, y saber cuándo un monorepo con Nx aporta más de lo que cuesta.
• Diagnosticar los fallos de arranque y de compilación más frecuentes: versión de Node incompatible, presupuesto excedido, NG0203, caché corrupta y mezcla de versiones de paquetes.

2.2 Historia y contexto: de AngularJS al Angular de hoy

Ningún framework se entiende sin su historia. Muchas decisiones de Angular que hoy parecen arbitrarias —la inyección de dependencias omnipresente, la obsesión por el tooling, el compilador propio— son respuestas concretas a problemas que el equipo sufrió en la primera versión. Merece la pena dedicarles unos minutos.

2.3 Definición y filosofía: framework completo y opinado

Angular es un framework de desarrollo de aplicaciones web, mantenido por Google, escrito en TypeScript, que proporciona en un único paquete versionado de forma conjunta el sistema de componentes, el enrutador, el cliente HTTP, los formularios, la inyección de dependencias, la internacionalización, el renderizado en servidor, las herramientas de compilación y el marco de pruebas. Esa frase larga contiene la diferencia esencial con una librería: React no es comparable a Angular; lo comparable es React más React Router más TanStack Query más React Hook Form más Vite más Vitest, cada uno con su ciclo de vida, su mantenedor y su criterio.

2.3.1 Qué significa «opinado» y por qué es una ventaja o un lastre

Un framework opinado (opinionated) tiene una respuesta preferente para cada pregunta de diseño: cómo se organiza un componente, cómo se obtiene una dependencia, cómo se navega, cómo se prueba. Esa opinión tiene un coste evidente —menos libertad— y una ventaja que solo se aprecia con el tiempo y con equipos grandes: la homogeneidad.

2.3.2 Qué problema resuelve realmente

• Consistencia entre equipos. Un servicio, un componente o una ruta se escriben igual en Madrid que en Bangalore. La revisión de código deja de discutir estructura y pasa a discutir lógica de negocio, que es donde aporta valor.
• Inyección de dependencias de primera clase. No es un detalle menor: es lo que permite sustituir una implementación por otra en pruebas, en distintos entornos o por configuración, sin tocar el código que la consume. Es el principio de inversión de dependencias de SOLID aplicado en el propio framework, y ningún otro framework de interfaz lo ofrece con esta profundidad.
• Herramientas integradas. Un solo CLI genera, sirve, compila, prueba, analiza y actualiza el proyecto. No hay que ensamblar y mantener una cadena de herramientas propia.
• Testabilidad por diseño. Los componentes son clases con dependencias explícitas; sustituirlas en un test es trivial. TestBed reconstruye el árbol de inyectores para probar en aislamiento.
• Actualizaciones asistidas. Este es el argumento más infravalorado. ng update no solo cambia números de versión: ejecuta migraciones de código que reescriben tus ficheros para adaptarlos a las APIs nuevas. En aplicaciones que viven diez años, esto es dinero.
• Tipado extremo a extremo. Con strictTemplates activado, incluso las expresiones de las plantillas se comprueban contra los tipos declarados. Un error de nombre de propiedad se detecta al compilar, no en producción.

2.3.3 Para quién NO es la mejor opción

La honestidad intelectual obliga a decir esto con claridad. Angular es una mala elección si:

• Necesitas un widget embebido en una página existente de otra tecnología. El coste de arranque del framework no se amortiza para un formulario de suscripción.
• El proyecto es una landing o un sitio de contenido donde lo que importa es el SEO y el tiempo hasta el primer pintado. Astro, Eleventy o incluso HTML plano ganan sin discusión.
• Trabajas solo o en pareja en un prototipo de dos semanas. La ceremonia de Angular es una inversión: si el proyecto no va a durar, no la recuperas.
• Tu equipo ya domina otro ecosistema y no hay una razón técnica de peso para cambiar. La productividad de un equipo experto en React supera casi siempre a la de un equipo aprendiendo Angular.
• El tamaño del bundle es el requisito número uno por encima de todo lo demás —una aplicación para mercados con conectividad muy limitada, por ejemplo—. Svelte o Preact producen artefactos más pequeños.

2.4 Comparación honesta con React, Vue y Svelte

Las comparaciones de frameworks suelen ser propaganda. Intentemos algo distinto: una tabla donde cada casilla describe un hecho verificable, y después unos criterios de elección explícitos. Ten presente que se compara Angular completo con el core de los demás; donde eso distorsiona, se indica.

2.4.1 Criterios de elección, sin diplomacia

• Elige Angular si el proyecto va a durar años, lo van a tocar varios equipos, hay rotación de personal, el dominio es complejo (formularios largos, permisos, informes) y valoras poder actualizar con un mandato. Es la elección natural en banca, seguros, salud, logística y administración pública.
• Elige React si necesitas el mayor mercado de talento posible, si vas a usar un meta-framework maduro para SSR y contenido, o si tu producto depende de un ecosistema muy específico (visualización, 3D, realidad aumentada) donde las mejores librerías nacen primero allí.
• Elige Vue si buscas el mejor equilibrio entre curva de aprendizaje y capacidades, si el equipo es pequeño y quieres productividad inmediata sin renunciar a un router y a un sistema de estado oficiales.
• Elige Svelte si el tamaño y el rendimiento en dispositivos modestos son requisitos duros, si el equipo es reducido y experimentado, y si aceptas un ecosistema más pequeño a cambio de un código fuente notablemente más corto.

2.5 Arquitectura interna: cómo funciona Angular por dentro

Angular no interpreta tus plantillas en tiempo de ejecución: las compila. Entender ese proceso explica de golpe por qué existe el CLI, por qué los errores de plantilla aparecen al compilar y por qué el tamaño del bundle depende de qué usas y no de qué instalas.

2.5.1 Compilación AOT frente a JIT

Históricamente hubo dos modos de compilar las plantillas de Angular:

• JIT (Just-In-Time, «justo a tiempo»): el compilador de Angular viajaba dentro del bundle y traducía las plantillas en el navegador, al arrancar la aplicación. Ventaja: compilación de desarrollo rápida. Inconvenientes: el compilador pesaba, el arranque era más lento y los errores de plantilla solo aparecían en tiempo de ejecución.
• AOT (Ahead-Of-Time, «por adelantado»): las plantillas se traducen a JavaScript durante la compilación, en tu máquina o en el servidor de integración continua. El compilador no viaja al navegador. Los errores de plantilla son errores de compilación.

Desde Angular 9, AOT es el modo por defecto también en desarrollo. El modo JIT sigue existiendo para casos muy concretos (algunos escenarios de pruebas y de carga dinámica), pero para el trabajo diario puedes considerar que Angular es un compilador. Esta es una diferencia cualitativa con la mayoría de sus competidores: cuando escribes {{ usuario.nombree }} con una errata, Angular te lo dice antes de arrancar.

PIPELINE DE COMPILACIÓN DE ANGULAR

  ┌──────────────────────┐   ┌──────────────────────┐
  │  componente.ts       │   │  componente.html     │
  │  @Component({...})   │   │  plantilla Angular   │
  │  class Componente    │   │  {{ }}  @if  @for    │
  └──────────┬───────────┘   └──────────┬───────────┘
             │                          │
             └───────────┬──────────────┘
                         ▼
        ┌────────────────────────────────────┐
        │  1. COMPILADOR DE ANGULAR (ngtsc)  │
        │     Analiza los decoradores y      │
        │     traduce la plantilla a         │
        │     instrucciones de renderizado   │
        └────────────────┬───────────────────┘
                         ▼
        ┌────────────────────────────────────┐
        │  2. SALIDA: campos estáticos en la │
        │     propia clase                   │
        │     ɵcmp = defineComponent({       │
        │       template: function(rf, ctx){ │
        │         ... elementStart / text /  │
        │         property / advance ...     │
        │       }})                          │
        └────────────────┬───────────────────┘
                         ▼
        ┌────────────────────────────────────┐
        │  3. TypeScript → JavaScript        │
        │     comprobación de tipos incluida │
        │     en plantillas (strictTemplates)│
        └────────────────┬───────────────────┘
                         ▼
        ┌────────────────────────────────────┐
        │  4. EMPAQUETADO (esbuild/Rollup)   │
        │     tree shaking · minificación    │
        │     división en trozos (chunks)    │
        │     hash en los nombres de fichero │
        └────────────────┬───────────────────┘
                         ▼
        ┌────────────────────────────────────┐
        │  5. dist/  →  navegador            │
        │     main-A1B2C3.js, chunk-*.js     │
        └────────────────────────────────────┘

2.5.2 Qué es Ivy y qué es la «localidad»

Ivy es el nombre del motor de compilación y renderizado que sustituyó a ViewEngine en Angular 9. Su idea central es la localidad (locality): para compilar un componente basta con la información contenida en ese componente, sin necesidad de analizar globalmente toda la aplicación ni de generar metadatos intermedios (los antiguos ficheros .metadata.json de ViewEngine).

Las consecuencias de la localidad son enormes y explican casi todo lo demás:

• Compilación incremental real. Si cambias un componente, solo se recompila ese componente. Los tiempos de recompilación en desarrollo bajan de segundos a milisegundos.
• Las librerías se distribuyen ya compiladas. Desaparece el paso ngcc que hacía falta al principio de la era Ivy para convertir librerías antiguas.
• Tree shaking del propio framework. Como veremos ahora mismo, el código generado importa exactamente las instrucciones que usa. Lo que no se usa no se importa, y lo que no se importa no entra en el bundle.
• Depuración comprensible. Las pilas de llamadas apuntan a funciones con nombre en lugar de a un intérprete genérico, y aparecen APIs de depuración como ng.getComponent($0) en la consola del navegador.

2.5.3 De la plantilla a las instrucciones de renderizado

Este es el punto que más sorprende a quien viene de React: una plantilla de Angular no se convierte en un árbol de objetos que describe la interfaz. Se convierte en una función que, al ejecutarse, llama a instrucciones que crean y actualizan nodos del DOM. Veámoslo con un ejemplo mínimo.

@Component({
  selector: 'app-saludo',
  template: `
    <h1>Hola, {{ nombre() }}</h1>
    <button (click)="saludar()">Saludar</button>
  `,
})
export class SaludoComponent {
  readonly nombre = signal('Ana');
  saludar(): void { /* ... */ }
}

// El compilador añade un campo estático a la propia clase.
// 'rf' son las "render flags": 1 = crear, 2 = actualizar.
SaludoComponent.ɵcmp = defineComponent({
  type: SaludoComponent,
  selectors: [['app-saludo']],
  decls: 4,        // número de nodos declarados
  vars: 1,         // número de expresiones enlazadas
  template: function SaludoComponent_Template(rf, ctx) {
    if (rf & 1) {                       // FASE DE CREACIÓN (una sola vez)
      elementStart(0, 'h1');
      text(1);                          // nodo de texto vacío, se rellena luego
      elementEnd();
      elementStart(2, 'button');
      listener('click', function () { return ctx.saludar(); });
      text(3, 'Saludar');
      elementEnd();
    }
    if (rf & 2) {                       // FASE DE ACTUALIZACIÓN (cada comprobación)
      advance(1);                       // sitúa el "puntero" en el nodo 1
      textInterpolate1('Hola, ', ctx.nombre(), '');
    }
  },
});
// Nota: los nombres reales van prefijados con ɵɵ (ɵɵelementStart, ɵɵadvance...).
// El prefijo indica API privada del framework: nunca la llames directamente.

Fíjate en tres cosas. Primera: hay dos fases separadas, creación y actualización, y la de actualización solo toca lo que puede cambiar. Segunda: cada nodo tiene un índice fijo conocido en tiempo de compilación, por lo que actualizar el texto es acceder a una posición de un array, no buscar en el DOM. Tercera, y decisiva: solo se importan las instrucciones que la plantilla necesita. Una plantilla sin @for no arrastra el código de repetición de listas.

2.5.4 Incremental DOM frente a Virtual DOM

La estrategia de Ivy se conoce como incremental DOM. La de React, virtual DOM. La diferencia se resume en qué se hace cuando hay que actualizar la pantalla.

2.5.5 El papel de Zone.js, a alto nivel

Nos falta una pieza: ¿quién decide cuándo se ejecuta la fase de actualización? Históricamente, Zone.js. Es una librería que parchea las APIs asíncronas del navegador —setTimeout, addEventListener, XMLHttpRequest, Promise— para saber cuándo empieza y cuándo termina cualquier tarea asíncrona. Cuando la cola de tareas de la zona de Angular se vacía, el framework deduce que «puede haber cambiado algo» y ejecuta un recorrido de detección de cambios.

La ventaja es la comodidad: escribes código normal y la vista se actualiza sola. El inconveniente es la imprecisión: Angular no sabe qué ha cambiado, solo que algo asíncrono ha ocurrido, así que comprueba de más. De ahí la dirección actual del framework, el modo zoneless, en el que las señales notifican con precisión qué vista hay que refrescar y Zone.js deja de ser necesario.

2.6 Instalación y CLI completo

2.6.1 Requisitos previos

Angular necesita Node.js y un gestor de paquetes. Cada versión mayor de Angular declara qué versiones de Node, TypeScript y RxJS admite, y el CLI se niega a funcionar —con un mensaje explícito— si la versión de Node está fuera de rango.

# Versiones instaladas
node --version          # p. ej. v22.14.0
npm --version           # p. ej. 10.9.2

# Gestión de versiones de Node con nvm (recomendado)
nvm install 22
nvm use 22
node --version > .nvmrc   # deja constancia de la versión del proyecto

2.6.2 Instalación global frente a npx

# CLI global fijo, instalado una vez hace dos años
npm install -g @angular/cli

# Consecuencia: trabajas en tres proyectos con
# Angular 17, 19 y 20, y tu 'ng' global es de la 16.
# Los generadores producen código de una versión
# y el proyecto espera otra. Los mensajes de error
# son confusos porque nadie mira la versión del CLI.
ng version   # dice 16.x mientras el proyecto es 20.x

# 1) Crear proyectos con npx: siempre la última versión
npx @angular/cli@latest new mi-app

# 2) Dentro del proyecto, usar SIEMPRE el CLI local
#    (el que está en node_modules y en package.json)
npx ng generate component tareas
npm run ng -- generate component tareas

# El CLI local está fijado en package.json, así que
# todo el equipo y la CI usan exactamente el mismo.
# Si además instalas uno global, mantenlo actualizado:
npm install -g @angular/cli@latest

2.6.3 ng new: crear el proyecto

npx @angular/cli@latest new gestor-tareas \
  --routing \                     # genera app.routes.ts y provideRouter
  --style=scss \                  # css | scss | sass | less
  --ssr=false \                   # renderizado en servidor: pregunta si se omite
  --package-manager=npm \         # npm | yarn | pnpm | cnpm | bun
  --prefix=app \                  # prefijo de los selectores: <app-tareas>
  --skip-tests=false \            # true omite los ficheros .spec.ts
  --skip-git=false                # true no inicializa el repositorio

# Opciones útiles adicionales:
#   --dry-run            muestra qué ficheros se crearían, sin escribir nada
#   --skip-install       no ejecuta npm install (útil en CI o sin red)
#   --minimal            sin pruebas ni configuración extra (prototipos)
#   --inline-template    plantilla dentro del .ts en lugar de fichero aparte
#   --inline-style       estilos dentro del .ts
#   --create-application=false   crea un espacio de trabajo vacío (monorepo)
#   --directory=carpeta  nombre de la carpeta si difiere del nombre del proyecto

# El catálogo completo de opciones de TU versión, siempre aquí:
ng new --help

2.6.4 ng generate: los schematics

Un schematic es un generador de código: una función que recibe unas opciones y produce o modifica ficheros del proyecto siguiendo las convenciones oficiales. No es un lujo cosmético: garantiza que todos los artefactos del proyecto se llamen, se sitúen y se registren igual, y evita las erratas de copiar y pegar.

# --dry-run (-d): imprime qué ficheros se crearían SIN escribir nada.
# Úsalo siempre la primera vez que pruebes un schematic desconocido.
ng g c features/facturas/tabla-facturas --dry-run

# Opciones habituales de 'component'
ng g c features/facturas/tabla-facturas \
  --change-detection=OnPush \   # estrategia de detección de cambios
  --inline-style \              # estilos en el .ts
  --inline-template \           # plantilla en el .ts
  --flat \                      # no crea subcarpeta propia
  --skip-tests \                # sin fichero .spec.ts
  --export                      # lo exporta del NgModule (solo código heredado)

# --project: obligatorio en espacios de trabajo con varias aplicaciones
ng g c cabecera --project=panel-admin

# Fijar valores por defecto para TODO el equipo, en angular.json:
#   "schematics": { "@schematics/angular:component": {
#       "changeDetection": "OnPush", "style": "scss" } }
# Así nadie tiene que acordarse de escribir las banderas.

2.6.5 El resto de mandatos

2.6.6 ng update y las migraciones automáticas

Este es el argumento comercial más sólido de Angular y conviene entender cómo funciona por dentro. Cuando ejecutas ng update @angular/core@20, el CLI hace cuatro cosas:

• Comprueba el estado del repositorio. Si hay cambios sin confirmar, se niega a continuar (salvo --allow-dirty). Quiere que puedas revisar el diff con claridad.
• Resuelve el árbol de dependencias y verifica que las versiones de todos los paquetes de Angular sean coherentes entre sí y con la de TypeScript y RxJS que exige la nueva versión.
• Actualiza package.json e instala.
• Ejecuta las migraciones declaradas por el paquete en su fichero migrations.json. Una migración es un schematic que analiza tu código con el árbol de sintaxis de TypeScript y lo reescribe: renombra APIs, cambia importaciones, transforma decoradores. No es una expresión regular: es una transformación consciente del AST.

# 0) Punto de partida limpio y una rama para la actualización
git status                 # debe estar limpio
git switch -c chore/actualizar-angular-20

# 1) Consultar la guía oficial ANTES de tocar nada.
#    update.angular.dev genera la lista exacta de pasos
#    para tu par de versiones (origen -> destino).

# 2) Nunca saltes versiones mayores. De la 18 a la 20 se pasa
#    por la 19: cada mayor trae sus propias migraciones.
ng update @angular/core@19 @angular/cli@19
git add -A && git commit -m "chore: Angular 19"
ng update @angular/core@20 @angular/cli@20

# 3) Revisar QUÉ ha reescrito la herramienta en tu código
git diff --stat
git diff src/

# 4) Ejecutar migraciones opcionales que no se aplican solas
ng update @angular/core --migrate-only --name=nombre-de-la-migracion

# 5) Verificar
npm run test -- --watch=false
ng build --configuration=production

# Migrar de NgModules a componentes standalone. Son tres pasos que
# se ejecutan en orden y por separado; se detallan en la sección 2.10.
ng generate @angular/core:standalone

# Otras migraciones útiles del paquete @angular/core
# (los nombres disponibles dependen de tu versión: consúltalos
#  en la guía de actualización antes de invocarlos)
ng generate @angular/core:control-flow      # *ngIf/*ngFor  ->  @if/@for
ng generate @angular/core:inject            # constructor   ->  inject()
ng generate @angular/core:signal-inputs     # @Input()      ->  input()
ng generate @angular/core:output-migration  # @Output()     ->  output()

2.7 Estructura del proyecto, archivo por archivo

Un proyecto recién creado con el CLI tiene unos veinte ficheros. Ninguno sobra y conviene saber qué hace cada uno antes de empezar a moverlos de sitio.

gestor-tareas/
│
├── angular.json            Configuración del ESPACIO DE TRABAJO: proyectos,
│                           builders, configuraciones, presupuestos, activos.
│                           Es el fichero más importante y el menos leído.
│
├── package.json            Dependencias y scripts de npm.
├── package-lock.json       Árbol exacto de versiones. VA AL REPOSITORIO.
│
├── tsconfig.json           Configuración base de TypeScript + angularCompilerOptions
├── tsconfig.app.json       Extiende la base: qué entra en la compilación de la app
├── tsconfig.spec.json      Extiende la base: qué entra en la compilación de tests
│
├── .editorconfig           Estilo de fichero (indentación, fin de línea)
├── .gitignore              Excluye node_modules/, dist/, .angular/
│
├── public/                 Activos estáticos copiados TAL CUAL a dist/
│   └── favicon.ico         (en versiones anteriores esta carpeta era src/assets/)
│
└── src/
    ├── main.ts             PUNTO DE ENTRADA. Arranca la aplicación.
    ├── index.html          Documento HTML base. Contiene <app-root></app-root>
    ├── styles.scss         Estilos globales (reset, tipografía, tema)
    │
    ├── environments/       (solo si ejecutas 'ng generate environments')
    │   ├── environment.ts             valores de PRODUCCIÓN
    │   └── environment.development.ts valores de DESARROLLO
    │
    └── app/
        ├── app.ts                  Componente raíz (clase)
        ├── app.html                Plantilla del componente raíz
        ├── app.scss                Estilos del componente raíz
        ├── app.spec.ts             Pruebas del componente raíz
        ├── app.config.ts           PROVEEDORES de la aplicación
        └── app.routes.ts           Tabla de rutas

NOTA SOBRE LOS NOMBRES: a partir de Angular v20 el CLI genera 'app.ts'
en lugar de 'app.component.ts' (desaparecen los sufijos .component,
.service, .directive...). Los proyectos anteriores conservan los sufijos
y ambos estilos son válidos. Comprueba qué genera TU versión con
'ng generate component prueba --dry-run'.

2.7.1 Qué hace exactamente cada fichero

2.8 angular.json en detalle

Casi nadie lee este fichero hasta que algo falla. Es un error: angular.json describe cómo se construye tu producto. Vamos por partes.

2.8.1 Anatomía: proyectos, targets y builders

La jerarquía es siempre la misma: el espacio de trabajo contiene proyectos; cada proyecto tiene unos targets (también llamados architect targets: build, serve, test, lint); cada target nombra un builder —la función que ejecuta el trabajo— y le pasa unas options; y cada target puede definir varias configurations que sobrescriben esas opciones.

angular.json
│
└─ projects
   └─ gestor-tareas
      ├─ projectType: "application"
      ├─ prefix: "app"
      ├─ sourceRoot: "src"
      ├─ schematics        ← valores por defecto de 'ng generate'
      └─ architect
         ├─ build
         │  ├─ builder: "@angular/build:application"
         │  ├─ options          ← base común
         │  └─ configurations
         │     ├─ production    ← optimiza, hashea, reemplaza ficheros
         │     ├─ staging       ← la que tú añadas
         │     └─ development   ← sourceMaps, sin optimizar
         ├─ serve
         │  ├─ builder: "@angular/build:dev-server"
         │  └─ configurations   ← apuntan a una configuración de 'build'
         ├─ test
         └─ lint

'ng build'          usa la configuración por defecto (production)
'ng build -c staging'      usa options + configurations.staging
'ng run gestor-tareas:build:staging'   forma larga y explícita

2.8.2 Un fragmento real, comentado

{
  "projects": {
    "gestor-tareas": {
      "projectType": "application",
      "prefix": "app",
      "sourceRoot": "src",

      "schematics": {
        "@schematics/angular:component": {
          "changeDetection": "OnPush",
          "style": "scss"
        }
      },

      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "browser": "src/main.ts",
            "index": "src/index.html",
            "tsConfig": "tsconfig.app.json",
            "outputPath": "dist/gestor-tareas",
            "assets": [ { "glob": "**/*", "input": "public" } ],
            "styles": [ "src/styles.scss" ],
            "scripts": [],
            "stylePreprocessorOptions": { "includePaths": ["src/estilos"] }
          },
          "configurations": {
            "production": {
              "budgets": [
                { "type": "initial",
                  "maximumWarning": "500kB", "maximumError": "1MB" },
                { "type": "anyComponentStyle",
                  "maximumWarning": "4kB", "maximumError": "8kB" }
              ],
              "fileReplacements": [
                { "replace": "src/environments/environment.ts",
                  "with":    "src/environments/environment.production.ts" }
              ],
              "optimization": true,
              "outputHashing": "all",
              "sourceMap": false
            },
            "development": {
              "optimization": false,
              "outputHashing": "none",
              "sourceMap": true,
              "extractLicenses": false
            }
          },
          "defaultConfiguration": "production"
        },
        "serve": {
          "builder": "@angular/build:dev-server",
          "configurations": {
            "production":  { "buildTarget": "gestor-tareas:build:production" },
            "development": { "buildTarget": "gestor-tareas:build:development" }
          },
          "defaultConfiguration": "development"
        }
      }
    }
  }
}

2.8.3 Las opciones que de verdad importan

2.8.4 Presupuestos: cómo leer un fallo de budget

Los presupuestos son un contrato con tu yo del futuro. Sin ellos, el bundle crece un poco cada semana y nadie lo nota hasta que la aplicación tarda ocho segundos en arrancar en un móvil de gama media.

$ ng build

✔ Building...

Initial chunk files   | Names         |  Raw size | Estimated transfer size
main-7QZK4XJ2.js      | main          |   1.42 MB |               312.05 kB
styles-K3MPQ8LA.css   | styles        |  84.31 kB |                9.12 kB
polyfills-B6TL9N1E.js | polyfills     |  34.58 kB |               11.32 kB

▲ [WARNING] bundle initial exceeded maximum budget.
  Budget 500.00 kB was not met by 1.02 MB with a total of 1.52 MB.

✘ [ERROR] bundle initial exceeded maximum budget.
  Budget 1.00 MB was not met by 520.13 kB with a total of 1.52 MB.

Error: Bundle exceeded maximum budget.

Cómo se interpreta. El presupuesto de tipo initial mide todo lo que el navegador debe descargar antes de poder pintar la primera pantalla. Aquí hay 1,52 MB sin comprimir frente a un tope de 1 MB. Ojo con una confusión muy extendida: el presupuesto compara contra el raw size (sin comprimir), no contra el estimated transfer size (comprimido), que es lo que realmente viaja por la red. Un bundle de 1,4 MB sin comprimir suele quedarse en unos 300 kB por el cable.

Qué hacer, en este orden. Uno: ejecuta ng build --stats-json y analiza el resultado (ver 2.13) para averiguar qué ocupa. Dos: si es una librería pesada usada en una sola pantalla, muévela detrás de una ruta con carga diferida o de un bloque @defer. Tres: comprueba que no estás importando la librería entera cuando solo necesitas una función. Cuatro, y solo cuando hayas agotado lo anterior: sube el presupuesto documentando en el mensaje del commit por qué. Subir el presupuesto sin investigar es apagar la alarma de incendios porque molesta el ruido.

// Importa TODA la librería para usar una función.
// El empaquetador no siempre puede eliminar el resto,
// y en el caso de lodash (CommonJS) desde luego no puede.
import _ from 'lodash';
import * as moment from 'moment';

const nombres = _.uniq(this.usuarios.map((u) => u.nombre));
const fecha = moment().format('DD/MM/YYYY');

// Resultado: ~70 kB de lodash y ~230 kB de moment
// (con todas sus localizaciones) en el bundle inicial.

// 1) La plataforma ya lo resuelve: no añadas dependencia.
const nombres = [...new Set(this.usuarios.map((u) => u.nombre))];
const fecha = new Intl.DateTimeFormat('es-ES').format(new Date());

// 2) Si necesitas una librería, elige una modular y
//    ESM, e importa solo lo que uses:
import { format } from 'date-fns';
import { es } from 'date-fns/locale';
const legible = format(new Date(), 'dd/MM/yyyy', { locale: es });

// Resultado: unos pocos kB, y solo los que se usan.

2.9 Arranque de la aplicación

2.9.1 El modelo antiguo y el actual

import { platformBrowserDynamic }
  from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';

platformBrowserDynamic()
  .bootstrapModule(AppModule)
  .catch((err) => console.error(err));

// Problemas de este modelo:
//  · 'platformBrowserDynamic' implica compilador JIT
//    disponible en el arranque.
//  · Toda la configuración vive dentro de un NgModule
//    con arrays 'imports' y 'providers' que crecen sin
//    control y que el empaquetador no puede podar.
//  · Importar un módulo arrastra TODO su contenido,
//    se use o no.

import { bootstrapApplication } from '@angular/platform-browser';
import { App } from './app/app';
import { appConfig } from './app/app.config';

bootstrapApplication(App, appConfig)
  .catch((err) => console.error(err));

// Ventajas:
//  · Sin compilador en tiempo de ejecución.
//  · La configuración es una lista PLANA de funciones
//    'provide*' que el empaquetador puede analizar:
//    lo que no se provee, no entra en el bundle.
//  · El fichero de arranque es trivial y estable;
//    la configuración vive aparte y se puede reutilizar
//    en las pruebas y en el renderizado en servidor.

FLUJO DE ARRANQUE DE UNA APLICACIÓN ANGULAR

  navegador descarga index.html
            │
            ▼
  carga main-HASH.js  (punto de entrada)
            │
            ▼
  ┌──────────────────────────────────────────────┐
  │ bootstrapApplication(App, appConfig)          │
  └───────────────────┬──────────────────────────┘
                      ▼
  ┌──────────────────────────────────────────────┐
  │ 1. Se crea la PLATAFORMA y el INYECTOR RAÍZ   │
  │    con todos los providers de appConfig       │
  │    (router, HttpClient, animaciones...)       │
  └───────────────────┬──────────────────────────┘
                      ▼
  ┌──────────────────────────────────────────────┐
  │ 2. INICIALIZADORES de la aplicación           │
  │    Angular ESPERA a que terminen (si          │
  │    devuelven una promesa u observable)        │
  │    antes de renderizar nada.                  │
  │    Ej.: cargar config remota, restaurar sesión│
  └───────────────────┬──────────────────────────┘
                      ▼
  ┌──────────────────────────────────────────────┐
  │ 3. Se instancia el COMPONENTE RAÍZ y se monta │
  │    en el elemento <app-root> del index.html   │
  └───────────────────┬──────────────────────────┘
                      ▼
  ┌──────────────────────────────────────────────┐
  │ 4. El ROUTER lee la URL actual, resuelve la   │
  │    ruta, ejecuta guards y resolvers y carga   │
  │    de forma diferida el chunk de la sección   │
  └───────────────────┬──────────────────────────┘
                      ▼
  ┌──────────────────────────────────────────────┐
  │ 5. PRIMERA DETECCIÓN DE CAMBIOS: se ejecuta   │
  │    la fase de creación de cada plantilla y    │
  │    aparecen los píxeles                       │
  └──────────────────────────────────────────────┘

2.9.2 Un app.config.ts de producción

import {
  ApplicationConfig, ErrorHandler, inject, isDevMode,
  provideBrowserGlobalErrorListeners,
} from '@angular/core';
import {
  provideRouter, withComponentInputBinding, withInMemoryScrolling,
  withRouterConfig, withViewTransitions,
} from '@angular/router';
import { provideHttpClient, withFetch, withInterceptors } from '@angular/common/http';
import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
import { rutas } from './app.routes';
import { interceptorToken } from './core/http/token.interceptor';
import { interceptorErrores } from './core/http/errores.interceptor';
import { ManejadorErroresGlobal } from './core/errores/manejador-errores';
import { ConfiguracionService } from './core/config/configuracion.service';

export const appConfig: ApplicationConfig = {
  providers: [
    // ── ENRUTADO ──────────────────────────────────────────────
    provideRouter(
      rutas,
      // Enlaza los parámetros de ruta directamente a los inputs
      // del componente: se acabó inyectar ActivatedRoute para todo.
      withComponentInputBinding(),
      // Restaura la posición de scroll al navegar atrás y salta
      // al ancla cuando la URL trae fragmento.
      withInMemoryScrolling({
        scrollPositionRestoration: 'enabled',
        anchorScrolling: 'enabled',
      }),
      // Transiciones de vista del navegador donde estén soportadas.
      withViewTransitions(),
      withRouterConfig({ onSameUrlNavigation: 'reload' }),
    ),

    // ── CLIENTE HTTP ──────────────────────────────────────────
    provideHttpClient(
      // Usa la API fetch en lugar de XMLHttpRequest: necesario
      // para el renderizado en servidor y para respuestas por streaming.
      withFetch(),
      // Los interceptores funcionales se ejecutan EN ORDEN.
      withInterceptors([interceptorToken, interceptorErrores]),
    ),

    // ── ANIMACIONES ───────────────────────────────────────────
    // La variante 'Async' carga el motor de animaciones de forma
    // diferida: no pesa en el bundle inicial si nada anima al arrancar.
    provideAnimationsAsync(),

    // ── ERRORES ───────────────────────────────────────────────
    // Captura errores no controlados de promesas y del propio
    // 'window' y los encamina hacia el ErrorHandler de Angular.
    provideBrowserGlobalErrorListeners(),
    { provide: ErrorHandler, useClass: ManejadorErroresGlobal },
  ],
};

import { ErrorHandler, Injectable, NgZone, inject, isDevMode } from '@angular/core';
import { HttpErrorResponse } from '@angular/common/http';
import { Router } from '@angular/router';

@Injectable({ providedIn: 'root' })
export class ManejadorErroresGlobal implements ErrorHandler {
  private readonly zona = inject(NgZone);
  private readonly router = inject(Router);
  private readonly telemetria = inject(TelemetriaService);

  handleError(error: unknown): void {
    // 1) En desarrollo, que se vea en consola con su pila completa.
    if (isDevMode()) {
      console.error('[Error no controlado]', error);
    }

    // 2) Los errores HTTP ya se tratan en el interceptor: aquí solo
    //    llegan los que nadie ha capturado. Evita duplicar avisos.
    if (error instanceof HttpErrorResponse) {
      if (error.status === 401) {
        // El ErrorHandler se ejecuta FUERA de la zona de Angular:
        // hay que volver a entrar para que la navegación
        // dispare la detección de cambios.
        this.zona.run(() => this.router.navigate(['/entrar']));
      }
      return;
    }

    // 3) Los errores de carga de un chunk suelen significar que se ha
    //    desplegado una versión nueva y el fichero antiguo ya no existe.
    const mensaje = error instanceof Error ? error.message : String(error);
    if (/ChunkLoadError|dynamically imported module/i.test(mensaje)) {
      location.reload();
      return;
    }

    // 4) Todo lo demás va a la telemetría, SIN datos personales.
    this.telemetria.registrarExcepcion(error);
  }
}

// Cargar configuración remota ANTES de que se pinte nada.
// Angular espera a que la promesa se resuelva.
//
// API actual (v19 y posteriores):
provideAppInitializer(() => {
  const config = inject(ConfiguracionService);
  return config.cargar();   // devuelve Promise<void> u Observable
}),

// API anterior, equivalente, todavía presente en muchos proyectos:
// {
//   provide: APP_INITIALIZER,
//   useFactory: (config: ConfiguracionService) => () => config.cargar(),
//   deps: [ConfiguracionService],
//   multi: true,
// },

// AVISO DE RENDIMIENTO: todo lo que pongas aquí RETRASA el primer
// pintado. Reserva este mecanismo para lo imprescindible (la URL de
// la API, la marca blanca del cliente) y carga el resto en paralelo
// una vez arrancada la aplicación.

2.10 Standalone frente a NgModules

2.10.1 Qué era un NgModule y qué problemas tenía

Un NgModule era una clase decorada que agrupaba componentes, directivas y pipes, declaraba qué otros módulos necesitaba y qué exportaba al exterior. Cumplía tres funciones a la vez: ámbito de compilación (qué directivas puede usar una plantilla), agrupación para carga diferida y contenedor de proveedores. Mezclar tres responsabilidades en un mismo artefacto es exactamente lo que aconseja evitar el principio de responsabilidad única, y las consecuencias fueron las esperables:

• Indirección constante. Para saber por qué una directiva funcionaba en una plantilla había que abrir el módulo, ver qué importaba y, con frecuencia, seguir la cadena a través de dos o tres módulos más.
• Ceremonia desproporcionada. Crear un componente exigía crearlo, declararlo en un módulo y exportarlo. Tres ficheros tocados para una unidad de interfaz.
• Peor tree shaking. Importar un módulo arrastraba todo lo declarado en él, aunque la plantilla usara un solo componente.
• El SharedModule monstruo. El patrón universal era un módulo compartido que exportaba todo; acababa importado en todas partes y arrastrando la mitad de la aplicación al bundle inicial.
• Errores desconcertantes. 'app-tarjeta' is not a known element significaba casi siempre un módulo mal importado, no un error real de plantilla.
• Barrera de entrada. Era el concepto que más costaba explicar a quien llegaba de React o de Vue, porque no tiene equivalente en ningún otro framework.

// FICHERO 1: el módulo
@NgModule({
  declarations: [ListaTareasComponent, FilaTareaComponent],
  imports: [CommonModule, ReactiveFormsModule, RouterModule],
  exports: [ListaTareasComponent],
  providers: [TareasService],
})
export class TareasModule {}

// FICHERO 2: el componente. Sus dependencias reales
// NO se ven aquí: están en el módulo de al lado.
@Component({
  selector: 'app-lista-tareas',
  templateUrl: './lista-tareas.component.html',
})
export class ListaTareasComponent {}

// Para leer este componente hay que abrir DOS ficheros
// y reconstruir mentalmente el ámbito de compilación.

// UN SOLO FICHERO. Las dependencias son explícitas
// y locales: se leen en el propio componente.
@Component({
  selector: 'app-lista-tareas',
  imports: [ReactiveFormsModule, RouterLink, FilaTarea],
  changeDetection: ChangeDetectionStrategy.OnPush,
  templateUrl: './lista-tareas.html',
})
export class ListaTareas {
  private readonly tareas = inject(TareasService);
}

// Ventajas concretas:
//  · El empaquetador ve exactamente qué se usa.
//  · Un import sobrante lo marca el linter como
//    'unused', cosa imposible con NgModules.
//  · 'standalone: true' es implícito desde la v19.

2.10.2 Cómo se migra

No a mano. Angular incluye una migración oficial que hace el trabajo pesado en tres pasos, y la clave está en ejecutarlos en orden y confirmar en el control de versiones entre uno y otro para poder revisar cada diff por separado.

# Paso 1 · Marcar componentes, directivas y pipes como standalone
#          y moverles sus dependencias desde el NgModule.
ng generate @angular/core:standalone
#   → elegir "Convert all components, directives and pipes to standalone"
git add -A && git commit -m "refactor: componentes standalone"

# Paso 2 · Eliminar los NgModules que han quedado sin contenido.
ng generate @angular/core:standalone
#   → elegir "Remove unnecessary NgModule classes"
git add -A && git commit -m "refactor: eliminar NgModules vacíos"

# Paso 3 · Cambiar el arranque a bootstrapApplication.
ng generate @angular/core:standalone
#   → elegir "Bootstrap the project using standalone APIs"
git add -A && git commit -m "refactor: arranque standalone"

# Después de cada paso, SIEMPRE:
npm run test -- --watch=false
ng build --configuration=production

2.10.3 Interoperabilidad entre ambos mundos

La migración puede ser gradual porque los dos modelos conviven de forma bidireccional. Merece la pena tener claras las dos direcciones:

2.11 Organización del código a escala

El CLI genera una carpeta app/ plana. Eso vale para el tutorial y deja de valer alrededor del componente número veinte. La pregunta que hay que responder es: ¿cuál es el criterio principal para agrupar ficheros? Hay dos respuestas posibles y solo una escala.

2.11.1 Agrupar por tipo frente a agrupar por funcionalidad

ESTRUCTURA RECOMENDADA A ESCALA

src/app/
│
├── core/                    Lo que existe UNA sola vez en la aplicación.
│   │                        Se usa en todas partes. No depende de features.
│   ├── auth/                sesión, guards de autenticación, permisos
│   ├── http/                interceptores (token, errores, reintentos)
│   ├── errores/             ErrorHandler global, tipos de error
│   ├── config/             configuración en tiempo de ejecución
│   └── modelos/             tipos e interfaces del dominio compartido
│
├── shared/                  Piezas REUTILIZABLES y SIN ESTADO de negocio.
│   │                        No depende de core ni de features.
│   ├── ui/                  botón, tarjeta, modal, tabla, paginador
│   ├── directivas/          autofoco, permiso, clic-fuera
│   ├── pipes/               tiempo-relativo, moneda-es, truncar
│   └── utilidades/          funciones puras, sin dependencias de Angular
│
├── features/                UNA CARPETA POR ÁREA FUNCIONAL.
│   ├── facturas/            Cada una se carga de forma diferida.
│   │   ├── facturas.routes.ts        rutas de la sección
│   │   ├── datos/                    servicios de acceso a la API
│   │   ├── modelos/                  tipos propios de esta feature
│   │   └── paginas/                  componentes con ruta
│   │       ├── lista-facturas/
│   │       └── detalle-factura/
│   ├── clientes/
│   └── informes/
│
├── layout/                  Cabecera, barra lateral, pie, contenedor
│
├── app.ts / app.html
├── app.config.ts
└── app.routes.ts            Solo rutas de primer nivel, todas diferidas

REGLA DE DEPENDENCIAS (la flecha significa "puede importar de"):

   features  ──▶  shared  ──▶  (nada del proyecto)
       │
       └──────▶  core    ──▶  shared

   features  ──✗──▶  otra feature      (prohibido: extrae a shared o core)
   shared    ──✗──▶  core o features   (prohibido: shared no sabe de negocio)
   core      ──✗──▶  features          (prohibido: crea ciclos)

2.11.2 Barrel files: la buena idea que envejece mal

Un barrel file es un index.ts que reexporta el contenido de una carpeta para poder importar desde un único sitio. Es cómodo y en aplicaciones grandes causa dos problemas serios.

// Un barril que reexporta TODO
export * from './boton/boton';
export * from './tabla/tabla';
export * from './editor-richtext/editor-richtext';  // arrastra 400 kB
export * from './grafico/grafico';                  // arrastra 180 kB

// El consumidor solo quiere el botón:
import { Boton } from '@app/shared/ui';

// PROBLEMA 1 · TREE SHAKING: el empaquetador debe analizar el
// módulo entero. Si el editor tiene efectos secundarios en el
// nivel superior, no puede podarlo y entran los 400 kB.
//
// PROBLEMA 2 · CICLOS: si un componente del barril importa a
// otro a través del propio barril, se crea una dependencia
// circular. Síntomas típicos y desconcertantes:
//   - "Cannot access 'X' before initialization" en el arranque
//   - NG0203 al inyectar dentro de un campo de clase
//   - un servicio que llega como 'undefined' sin motivo aparente
//
// PROBLEMA 3 · COMPILACIÓN: cualquier cambio en cualquier
// fichero del barril invalida a todos sus consumidores.

// Alias de rutas en lugar de barriles: rutas cortas
// SIN indirección y sin riesgo de ciclos.
{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@core/*":     ["src/app/core/*"],
      "@shared/*":   ["src/app/shared/*"],
      "@features/*": ["src/app/features/*"]
    }
  }
}
// Consumo: se importa el fichero concreto.
//   import { Boton } from '@shared/ui/boton/boton';
//
// Ventajas:
//  · El empaquetador ve la dependencia exacta.
//  · Imposible crear un ciclo a través del barril.
//  · Al leer el import sabes DÓNDE está el fichero.
//
// Si aun así quieres barriles, limítalos al borde
// PÚBLICO de una librería (el public-api.ts de una
// librería publicable) y nunca dentro de una carpeta
// cuyos ficheros se importen entre sí.

2.11.3 Convenciones de nombres

• Ficheros y carpetas en kebab-case: lista-facturas/, tiempo-relativo.ts. Nunca espacios ni mayúsculas: hay sistemas de ficheros sensibles a mayúsculas y otros que no, y esa diferencia rompe la integración continua de formas muy difíciles de depurar.
• Clases en PascalCase: ListaFacturas, FacturasService.
• Un artefacto por fichero y el nombre del fichero igual al de su artefacto principal.
• Prefijo de selector coherente con el prefix del proyecto: app-lista-facturas. En un monorepo, un prefijo por librería (ui-boton, fact-lista) evita colisiones.
• Sufijos: los proyectos anteriores a la v20 usan .component.ts, .service.ts, .pipe.ts; los nuevos generan nombres sin sufijo. Ambos son válidos. Lo que no es válido es mezclar los dos criterios en el mismo repositorio: elige uno y escríbelo en la guía de estilo del equipo.
• Idioma: decide si el dominio se escribe en español o en inglés y respétalo. Lo peor es getFacturasPendientes() junto a obtenerInvoiceList().

2.11.4 Cuándo pasar a un monorepo con Nx

Nx es un sistema de construcción para monorepos que se integra con Angular y sustituye o envuelve al CLI. No es «Angular avanzado»: es una herramienta de escala que aporta cosas concretas.

• Grafo de dependencias. Nx analiza las importaciones reales y construye el grafo del proyecto. Puedes visualizarlo y, sobre todo, preguntarle qué proyectos se ven afectados por un cambio concreto.
• Ejecución por afectación. En un pull request, en lugar de compilar y probar los cuarenta proyectos, Nx ejecuta solo los afectados por los ficheros tocados. En un monorepo grande, la diferencia es de cuarenta minutos a cuatro.
• Caché de tareas. Si una tarea ya se ejecutó con exactamente las mismas entradas, se reutiliza el resultado guardado en lugar de repetirla. Con caché remota compartida, el segundo desarrollador que compile una rama obtiene el resultado del primero al instante.
• Reglas de límites entre módulos. La regla de lint @nx/enforce-module-boundaries convierte en error de compilación lo que en un proyecto normal es solo una convención escrita en un documento que nadie lee. Se etiqueta cada librería (type:feature, type:ui, scope:facturas) y se declara qué puede importar qué.
• Generadores propios. Además de los de Angular, puedes escribir generadores para las convenciones de tu empresa.

2.12 Configuración por entornos

2.12.1 Configuración en tiempo de compilación

El mecanismo clásico de Angular es el reemplazo de ficheros. Se genera con ng generate environments, que crea la carpeta y además escribe el fileReplacements correspondiente en angular.json.

// ── environment.ts  (el que se importa SIEMPRE en el código) ──
// Contiene los valores de PRODUCCIÓN. Es el fichero por defecto.
export const environment = {
  produccion: true,
  apiUrl: 'https://api.empresa.com/v1',
  version: '2.4.0',
  registroNivel: 'error' as const,
};

// ── environment.development.ts ──
export const environment = {
  produccion: false,
  apiUrl: 'http://localhost:3000/api/v1',
  version: 'dev',
  registroNivel: 'debug' as const,
};

// ── Uso en el código: SIEMPRE se importa el fichero base ──
import { environment } from '../environments/environment';
private readonly base = environment.apiUrl;
// Durante la compilación de desarrollo, el builder sustituye
// físicamente el módulo por el de desarrollo. El código
// consumidor no se entera y no hay ningún 'if' en el bundle.

export const environment = {
  apiUrl: 'https://api.empresa.com',

  // TODO ESTO ES PÚBLICO. Está en el bundle.
  claveApiStripe: 'sk_live_51H8...',   // clave SECRETA
  secretoJwt: 'mi-secreto-de-firma',   // firma de tokens
  usuarioBd: 'admin',
  passwordBd: 'Passw0rd!',
  claveCifrado: 'AES256-clave-maestra',
};

// Consecuencia real: cualquiera abre las DevTools,
// busca "sk_live" en los ficheros descargados y tiene
// tu clave de cobros. Ha ocurrido muchas veces y sale
// carísimo.

export const environment = {
  produccion: true,

  // Solo datos que YA son públicos por naturaleza:
  apiUrl: 'https://api.empresa.com/v1',
  version: '2.4.0',

  // Clave PUBLICABLE de Stripe: está diseñada para
  // vivir en el cliente y no permite cobrar por sí sola.
  clavePublicaStripe: 'pk_live_51H8...',

  // Identificadores públicos de OAuth: el flujo con PKCE
  // no requiere secreto de cliente en aplicaciones SPA.
  clienteOauthId: 'gestor-tareas-web',
};

// Todo lo secreto vive en el BACKEND. El frontend pide
// al backend, y el backend habla con Stripe usando su
// clave secreta, que nunca sale del servidor.

2.12.2 Configuración en tiempo de ejecución

El reemplazo de ficheros tiene una limitación importante: obliga a compilar una vez por entorno. Si tienes desarrollo, integración, preproducción y producción, son cuatro artefactos distintos, y el que pruebas en preproducción no es exactamente el que despliegas en producción. Para muchos equipos eso es inaceptable, y para el modelo de contenedores («compila una vez, despliega en todas partes») directamente no funciona.

La alternativa es cargar la configuración al arrancar, desde un fichero JSON estático que se sustituye en cada despliegue.

import { Injectable, inject, signal } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';

export interface ConfiguracionApp {
  readonly apiUrl: string;
  readonly entorno: 'desarrollo' | 'integracion' | 'preproduccion' | 'produccion';
  readonly funcionesActivas: readonly string[];
}

@Injectable({ providedIn: 'root' })
export class ConfiguracionService {
  private readonly http = inject(HttpClient);
  private readonly _config = signal<ConfiguracionApp | null>(null);
  readonly config = this._config.asReadonly();

  /** Se invoca desde provideAppInitializer: Angular espera a la promesa. */
  async cargar(): Promise<void> {
    // El fichero vive en public/, así que se copia sin procesar a dist/.
    // En el despliegue se monta encima el config.json del entorno
    // (un volumen de Kubernetes, una capa de la imagen, un ConfigMap...).
    const config = await firstValueFrom(
      this.http.get<ConfiguracionApp>('/config.json'),
    );
    this._config.set(config);
  }

  /** Lectura segura: si esto lanza, el inicializador no se ejecutó. */
  get valor(): ConfiguracionApp {
    const c = this._config();
    if (!c) throw new Error('Configuración no cargada: falta el inicializador');
    return c;
  }
}

2.13 Rendimiento de la compilación y del arranque

2.13.1 El builder basado en esbuild y Vite

Durante años Angular compiló con webpack. Desde la v17 el builder por defecto para proyectos nuevos es el llamado application, que usa esbuild para el empaquetado y Vite como servidor de desarrollo. Las diferencias en la práctica:

• Compilación de producción varias veces más rápida. esbuild está escrito en Go y paraleliza de forma agresiva. Los tiempos típicos bajan de minutos a decenas de segundos.
• Servidor de desarrollo casi instantáneo. Vite no empaqueta en desarrollo: sirve módulos ES nativos al navegador y transforma solo lo que se pide. El arranque deja de depender del tamaño de la aplicación.
• Recarga en caliente de estilos y plantillas sin perder el estado de la pantalla.
• Salida moderna: genera módulos ES, y no las parejas de bundles diferenciales de la época de webpack.

2.13.2 Analizar el bundle

# 1) Compilar generando el fichero de estadísticas
ng build --configuration=production --stats-json

# 2) IMPORTANTE: el formato de stats.json depende del builder.
#    · builder ':browser'     -> formato de webpack
#    · builder ':application'  -> "metafile" de esbuild
#    Las herramientas NO son intercambiables.

# Para el builder moderno (esbuild): esbuild-visualizer
npx esbuild-visualizer --metadata dist/gestor-tareas/stats.json \
  --filename analisis.html --open

# Alternativa sin instalar nada: subir el metafile al
# analizador oficial en esbuild.github.io/analyze/

# Para el builder antiguo (webpack): webpack-bundle-analyzer
npx webpack-bundle-analyzer dist/gestor-tareas/stats.json

# 3) Vista rápida sin herramientas: los tamaños por chunk que el
#    propio 'ng build' imprime al terminar. Compáralos entre commits.

Qué buscar en el análisis. Primero, cualquier librería en el chunk inicial que solo se use en una pantalla concreta: es candidata a carga diferida. Segundo, dependencias duplicadas en varias versiones (dos copias de la misma librería suele significar un package-lock.json desordenado o dos rutas de importación distintas al mismo paquete). Tercero, locales e idiomas completos de librerías de fechas o de internacionalización. Cuarto, imágenes o fuentes incrustadas en base64 que serían más eficientes como ficheros aparte.

2.13.3 Qué hacer cuando el build tarda demasiado

• Comprueba la caché primero. ng cache info te dice si está activa y cuánto ocupa. En integración continua suele estar desactivada por defecto en entornos de solo escritura: si la activas y persistes .angular/cache entre ejecuciones, los tiempos caen a la mitad.
• Mide antes de optimizar. Ejecuta ng build --verbose o cronometra las fases: casi siempre el culpable es identificable y concreto.
• Revisa el preprocesador de estilos. Un @use o @import de un fichero de variables grande en cada componente multiplica el trabajo de Sass por el número de componentes. Usa stylePreprocessorOptions.includePaths y limita los imports globales a variables y mixins, nunca a reglas CSS.
• Vigila el número de ficheros que entra en la compilación: un include demasiado amplio en tsconfig.app.json puede estar arrastrando ficheros de pruebas o generados. Y desactiva los mapas de fuentes en la compilación de CI si no los subes a ninguna parte, porque generarlos cuesta tiempo y memoria.
• Sube la memoria de Node si ves JavaScript heap out of memory: NODE_OPTIONS=--max-old-space-size=8192 ng build. Es un parche, pero desbloquea mientras investigas la causa.
• Si nada de esto basta, el problema es de arquitectura: tienes un monolito de frontend y toca dividirlo. Ahí es donde Nx y su ejecución por afectación empiezan a compensar.

2.13.4 El arranque en el navegador

• Lazy loading por ruta. Todo lo que no sea la primera pantalla debe estar detrás de un loadComponent o un loadChildren. Es la optimización con mejor relación entre esfuerzo y resultado, con diferencia.
• @defer dentro de una pantalla para bloques pesados y secundarios: un gráfico, un editor de texto enriquecido, un mapa. Se descarga cuando el bloque entra en el viewport o cuando el usuario interactúa.
• Presupuestos ajustados para que la degradación se detecte en el pull request y no en producción seis meses después, y mucho cuidado con lo que pones en el inicializador de la aplicación: cada llamada que hagas ahí retrasa el primer pintado para todos los usuarios.
• Renderizado en servidor con hidratación si el tiempo hasta el primer contenido importa de verdad. Se añade con ng add @angular/ssr y se trata en el capítulo 7.

2.14 Errores comunes y cómo solucionarlos

2.15 Buenas y malas prácticas

2.16 Preguntas frecuentes

2.17 Ejercicios

"build": {
  "configurations": {
    "staging": {
      "budgets": [
        { "type": "initial", "maximumWarning": "700kB", "maximumError": "1.5MB" }
      ],
      "fileReplacements": [
        { "replace": "src/environments/environment.ts",
          "with":    "src/environments/environment.staging.ts" }
      ],
      "optimization": true,
      "outputHashing": "all",
      "sourceMap": { "scripts": true, "styles": true, "hidden": false }
    }
  }
},
"serve": {
  "configurations": {
    "staging": { "buildTarget": "gestor-tareas:build:staging" }
  }
}

// public/config.json  ← se copia sin procesar a dist/
// { "apiUrl": "https://api.empresa.com/v1", "entorno": "produccion",
//   "funcionesActivas": ["facturacion-v2"] }

// app.config.ts
providers: [
  provideHttpClient(withFetch()),
  // El inicializador se ejecuta ANTES de crear el componente raíz.
  // Angular espera a la promesa: nada se pinta hasta que resuelve.
  provideAppInitializer(() => inject(ConfiguracionService).cargar()),
],

// configuracion.service.ts (fragmento clave)
async cargar(): Promise<void> {
  try {
    const c = await firstValueFrom(
      this.http.get<ConfiguracionApp>('/config.json'),
    );
    this._config.set(c);
  } catch {
    // DECISIÓN DE DISEÑO: si la configuración no carga, la aplicación
    // no puede funcionar. Es preferible fallar de forma ruidosa y
    // explícita que arrancar con una apiUrl 'undefined' y producir
    // cien errores incomprensibles en cascada.
    throw new Error('No se pudo cargar /config.json');
  }
}

// Verificación: en la pestaña de red, /config.json debe aparecer
// ANTES de cualquier otra llamada a la API y antes del primer
// pintado. Si ves peticiones de negocio previas, algún servicio
// se está instanciando fuera del inicializador.

2.18 Resumen del capítulo

2.19 Recursos adicionales

• angular.dev — la documentación oficial actual. Sustituye a angular.io, que documenta versiones antiguas: comprueba siempre en qué sitio estás antes de seguir un tutorial.
• angular.dev/cli — referencia completa del CLI, mandato a mandato, con todas las opciones de ng new, ng generate, ng build y ng update.
• update.angular.dev — la guía interactiva de actualización: eliges versión de origen y de destino y genera la lista exacta de pasos y de cambios incompatibles. Consúltala antes de cada actualización mayor.
• Angular · Compatibilidad de versiones — la tabla que dice qué versiones de Node, TypeScript y RxJS admite cada versión de Angular, y el calendario de soporte a largo plazo.
• Angular · Configuración del espacio de trabajo — la referencia exhaustiva de todas las claves de angular.json.
• Blog oficial de Angular — los anuncios de cada versión mayor, con las razones de diseño detrás de cada cambio. La mejor fuente para entender hacia dónde va el framework.
• nx.dev — documentación de Nx: monorepos, grafo de dependencias, caché de tareas y reglas de límites entre módulos.
• esbuild · Bundle Size Analyzer — analizador oficial del metafile que genera ng build --stats-json con el builder moderno.
• Angular · CHANGELOG — el detalle exacto de qué cambió en cada versión, incluidos los cambios incompatibles y las migraciones asociadas.