Integrating Third-Party Scripts and CSS into Your Angular App

When building real-world applications in Angular, you frequently need to integrate third-party libraries: analytics tracking scripts (Google Analytics, Mixpanel), payment gateways (Stripe, PayPal SDKs), charting libraries, or existing CSS frameworks.

While you could manually paste <script> tags into index.html, doing so bypasses the Angular build pipeline, compromises bundle optimization, and often causes Server-Side Rendering (SSR) crashes.

⚡ Using Modern Angular (v17+)? Jump directly to Modern Angular: SSR Safety with afterNextRender and Standalone Schemas to see how to load scripts safely in hydration-enabled apps.

In this guide, we will explore how to configure third-party assets in angular.json, create separate named bundles, and dynamically load external scripts safely in modern Angular.

Let's begin by looking at the built-in angular.json pipeline.

1. Build-Time Integration with angular.json 📦

The cleanest way to include global CSS and JavaScript files that must be available application-wide is through the workspace configuration file angular.json.

Navigate to architect > build > options and locate the styles and scripts arrays:

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

When you run ng build, the Angular CLI automatically minifies, tree-shakes (where applicable), hashes, and bundles these files into your initial distribution.

Now, what if you have a heavy script that is only used on a specific page? Let's see how to create separate named bundles.

2. Separate Named Bundles for Heavy Scripts 🗂️

If you have a large library (like a 3D canvas viewer or specialized uploader) that you do not want to bloat your initial main.js bundle with, you can configure it as a separate chunk in 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"
    }
  ]
}

Options Explained:

• input: Path to the source file (relative to workspace root).
• bundleName: Name of the generated output file (e.g. dist/my-app/custom-uploader-script.js).
• inject: Set to false if you want to load the script on-demand via JavaScript instead of including it on initial page load.

Now let's see how to dynamically load scripts at runtime in a component.

3. Modern Angular: Dynamic Scripts & SSR Safety with afterNextRender ⚡

With Angular's modern hydration and Server-Side Rendering (SSR) enabled by default, attempting to access document or window directly during component initialization will crash the server renderer with ReferenceError: document is not defined.

In modern Angular (v17+), we use the afterNextRender lifecycle hook to guarantee that script injection only runs once the component has rendered on the client browser.

Reusable Dynamic Script Service

// 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);
    });
  }
}

Safe Usage Inside a Standalone Component

// 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() {
    // Guaranteed to only execute in the browser DOM (SSR Safe!)
    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);
      }
    });
  }
}

Now let's look at integrating Web Components / Custom Elements.

4. Using Third-Party Web Components with CUSTOM_ELEMENTS_SCHEMA 🧩

If your third-party script defines a standard Web Component (e.g. <stripe-pricing-table> or <media-player>), Angular's template compiler will emit an error by default because it doesn't recognize the custom HTML tag.

To allow custom elements in modern Standalone components:

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
 
@Component({
  selector: 'app-custom-widget',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // 👈 Tells Angular to allow unknown custom tags
  template: `
    <stripe-pricing-table
      pricing-table-id="prctbl_12345"
      publishable-key="pk_live_12345"
    ></stripe-pricing-table>
  `
})
export class CustomWidgetComponent {}

Integration Strategy Comparison 📊

Recap 🛠️

To keep your Angular application fast, maintainable, and SSR-safe when adding third-party code:

1. Use angular.json for global build-time stylesheets and scripts.
2. Use inject(DOCUMENT) and afterNextRender() for client-only dynamic script injection (avoiding SSR breakage).
3. Use CUSTOM_ELEMENTS_SCHEMA whenever embedding custom Web Component tags in your templates.

For more modern Angular architectural guides, check out my articles on How to Use Route Parameters in Angular and How to Use ng-template, ng-container, and ng-content!