Cómo integrar scripts y CSS de terceros en tu aplicación Angular

Cuando construyo aplicaciones reales en Angular, con frecuencia necesito integrar librerías externas: scripts de analítica (Google Analytics, Mixpanel), pasarelas de pago (SDKs de Stripe o PayPal), librerías de gráficas o frameworks de CSS existentes.

Aunque podrías pegar etiquetas <script> a mano en el archivo index.html, hacer eso se salta todo el pipeline de compilación de Angular, afecta la optimización de los bundles y muchas veces provoca caídas del servidor cuando trabajas con Server-Side Rendering (SSR).

⚡ ¿Usas Angular Moderno (v17+)? Salta directo a Angular Moderno: scripts dinámicos y compatibilidad con SSR usando afterNextRender para ver cómo cargar scripts de forma segura en aplicaciones con hidratación.

En este artículo te muestro cómo configurar recursos de terceros en angular.json, cómo crear bundles separados con nombre y cómo cargar scripts externos dinámicamente sin romper SSR en versiones modernas de Angular.

Empecemos revisando el pipeline integrado de angular.json.

1. Integración en tiempo de compilación con angular.json 📦

La forma más limpia de incluir archivos globales de CSS y JavaScript que deben estar disponibles en toda la aplicación es a través del archivo de configuración angular.json.

Ve a architect > build > options y ubica los arreglos styles y scripts:

{
  "architect": {
    "build": {
      "options": {
        "styles": [
          "src/styles.css",
          "node_modules/bootstrap/dist/css/bootstrap.min.css"
        ],
        "scripts": [
          "node_modules/chart.js/dist/chart.umd.js"
        ]
      }
    }
  }
}

Cuando ejecutas ng build, la CLI de Angular minifica, optimiza (tree-shaking cuando aplica), genera los hashes correspondientes y empaqueta estos archivos directamente en tus bundles iniciales de distribución.

Ahora bien, ¿qué pasa si tienes un script muy pesado que solo se usa en una página en particular? Veamos cómo crear bundles independientes con nombre propio.

2. Bundles independientes con nombre para scripts pesados 🗂️

Si tienes una librería de gran tamaño (como un visor 3D para canvas o un componente de subida de archivos especializado) y no quieres que engorde tu bundle inicial main.js, puedes configurarla como un chunk separado en angular.json:

{
  "styles": [
    "src/styles.css",
    {
      "input": "src/assets/custom-uploader/uploader.css",
      "inject": true,
      "bundleName": "custom-uploader-styles"
    }
  ],
  "scripts": [
    {
      "input": "src/assets/custom-uploader/uploader.js",
      "inject": false,
      "bundleName": "custom-uploader-script"
    }
  ]
}

Explicación de las opciones:

• input: Ruta al archivo fuente (relativa a la raíz del espacio de trabajo).
• bundleName: Nombre del archivo generado en la salida (por ejemplo, dist/my-app/custom-uploader-script.js).
• inject: Configúralo en false si quieres cargar el script bajo demanda mediante JavaScript en vez de incluirlo en la carga inicial de la página.

Ahora veamos cómo cargar scripts dinámicamente en tiempo de ejecución dentro de un componente.

3. Angular Moderno: scripts dinámicos y compatibilidad con SSR usando afterNextRender ⚡

Con la hidratación moderna y Server-Side Rendering (SSR) habilitados por defecto en Angular, intentar acceder directamente a document o window durante la inicialización de un componente romperá la renderización en el servidor con un error ReferenceError: document is not defined.

En Angular moderno (v17+), usamos el hook de ciclo de vida afterNextRender para garantizar que la inyección del script solo se ejecute una vez que el componente se haya renderizado en el navegador del cliente.

Servicio reutilizable para cargar scripts dinámicos

// script-loader.service.ts
import { Injectable, inject } from '@angular/core';
import { DOCUMENT } from '@angular/common';
 
@Injectable({ providedIn: 'root' })
export class ScriptLoaderService {
  private readonly document = inject(DOCUMENT);
  private readonly loadedScripts = new Set<string>();
 
  loadScript(src: string): Promise<void> {
    if (this.loadedScripts.has(src)) {
      return Promise.resolve();
    }
 
    return new Promise((resolve, reject) => {
      const script = this.document.createElement('script');
      script.type = 'text/javascript';
      script.src = src;
      script.async = true;
      script.onload = () => {
        this.loadedScripts.add(src);
        resolve();
      };
      script.onerror = (err) => reject(err);
      this.document.head.appendChild(script);
    });
  }
}

Uso seguro dentro de un componente Standalone

// payment-checkout.component.ts
import { Component, inject, afterNextRender, signal } from '@angular/core';
import { ScriptLoaderService } from './script-loader.service';
 
@Component({
  selector: 'app-payment-checkout',
  standalone: true,
  template: `
    <div class="checkout-card p-6 border rounded-xl">
      <h2>Complete Your Purchase</h2>
 
      @if (scriptReady()) {
        <div id="paypal-button-container"></div>
      } @else {
        <p class="text-neutral-500">Loading payment gateway securely...</p>
      }
    </div>
  `
})
export class PaymentCheckoutComponent {
  private readonly scriptLoader = inject(ScriptLoaderService);
  readonly scriptReady = signal(false);
 
  constructor() {
    // Se ejecuta únicamente en el DOM del navegador (seguro con SSR)
    afterNextRender(async () => {
      try {
        await this.scriptLoader.loadScript('https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID');
        this.scriptReady.set(true);
      } catch (err) {
        console.error('Failed to load payment SDK:', err);
      }
    });
  }
}

Ahora revisemos cómo integrar Web Components y Custom Elements en nuestras plantillas.

4. Uso de Web Components de terceros con CUSTOM_ELEMENTS_SCHEMA 🧩

Si tu script de terceros define un Web Component estándar (por ejemplo, <stripe-pricing-table> o <media-player>), el compilador de plantillas de Angular emitirá un error por defecto porque no reconoce esa etiqueta HTML personalizada.

Para permitir elementos personalizados en componentes Standalone modernos:

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
 
@Component({
  selector: 'app-custom-widget',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // 👈 Le indica a Angular que permita etiquetas personalizadas desconocidas
  template: `
    <stripe-pricing-table
      pricing-table-id="prctbl_12345"
      publishable-key="pk_live_12345"
    ></stripe-pricing-table>
  `
})
export class CustomWidgetComponent {}

Comparativa de estrategias de integración 📊

Resumen 🛠️

Para mantener tu aplicación de Angular rápida, mantenible y segura con SSR al incorporar código de terceros:

1. Usa angular.json para hojas de estilo y scripts globales en tiempo de compilación.
2. Usa inject(DOCUMENT) y afterNextRender() para inyectar scripts dinámicos solo en el cliente (evitando roturas en SSR).
3. Usa CUSTOM_ELEMENTS_SCHEMA siempre que utilices etiquetas de Web Components personalizados en tus plantillas.

Si quieres seguir explorando patrones de arquitectura en Angular moderno, te recomiendo leer mis artículos sobre cómo usar parámetros de ruta en Angular y cómo usar ng-template, ng-container y ng-content.