Angular Server-Side Configuration

Common errors

• TS2304: Cannot find name 'process'.

  cause The Angular CLI compiler became stricter with global typings for `process` in Angular v19, leading to this error when `process.env` is accessed directly.
  fix Add `"node"` to the `types` array in your `tsconfig.app.json` (e.g., `"types": ["node"]`) or set `"skipLibCheck": true` in your project's main `tsconfig.json`.

• Error: The 'build' and 'dev-server' experimental builders have been removed.

  cause Attempting to use the experimental Angular CLI builders (`angular-server-side-configuration:build` or `:serve`) which were removed in version 20.0.0.
  fix Update your `angular.json` configuration to use the standard `ngsscbuild` builder (`ng run your-project-name:ngsscbuild:production`) and remove any references to the deprecated experimental builders.

• Environment variable 'YOUR_VAR' is undefined when accessed via `NgsscService`.

  cause The environment variable was not set in the shell before running the native CLI insert command, or the `ngsscbuild` builder didn't correctly identify its usage during the build step.
  fix Ensure the environment variable (e.g., `NG_APP_YOUR_VAR`) is set in the environment where the native CLI command (e.g., `ngssc insert`) is executed. Verify that your `ngsscbuild` configuration in `angular.json` has an appropriate `searchPattern` that includes the files where `YOUR_VAR` is used.

Warnings

• breaking Upgrading to v20 requires an upgrade to Angular 20. Additionally, the experimental build and dev-server builders introduced in earlier versions have been completely removed.
  Fix: Ensure your project is compatible with Angular 20. Remove any references to the experimental 'build' and 'dev-server' builders from your `angular.json` configuration and use the standard 'ngsscbuild' builder.
• breaking With v19, the minified and 32-bit binaries that facilitate server-side configuration injection were removed. Projects relying on these specific binary distributions will no longer function as expected.
  Fix: Update your deployment scripts or Dockerfiles to use the standard 64-bit binaries. The deprecation notice for these binaries was issued in v18.1.0.
• gotcha Angular CLI compiler became stricter with global typings in v19, leading to 'Cannot find name 'process'' errors when accessing `process.env` directly.
  Fix: Add `"node"` to the `types` entry in your `tsconfig.app.json` (e.g., `"types": ["node"]`) or set `"skipLibCheck": true` in your main `tsconfig.json` (if not already set).
• breaking The default `searchPattern` for environment variables changed in v16 to `{sourceRoot}/**/environments/environment*.ts` for improved security and to follow 'Secure by default' principles.
  Fix: If your project uses environment variables in files outside `environments/environment*.ts` (e.g., `app.config.ts`), you must update the `searchPattern` entry in your `ngsscbuild` block within `angular.json` to include those paths.
• gotcha With version 15, the `ngsscEnvironmentFile` option became redundant and can be removed, as the builder now searches all files for environment variable usages. This change also introduced a potential information disclosure vulnerability in v15.0 if sensitive environment variables were present in other files.
  Fix: Remove the `ngsscEnvironmentFile` option from `angular.json`. For v15.0, immediately upgrade to v15.1 or later to leverage the `searchPattern` option, which mitigates the information disclosure risk by restricting the lookup path.

Install

• npm install angular-server-side-configuration npm
• yarn add angular-server-side-configuration yarn
• pnpm add angular-server-side-configuration pnpm

Imports

• ngssc

  ng add angular-server-side-configuration

  Initial setup is typically done via the Angular CLI's 'ng add' schematic, which configures `angular.json` and optionally adds imports to your application modules/environments.
• NgsscModule
  wrong:

  import NgsscModule from 'angular-server-side-configuration';

  correct:

  import { NgsscModule } from 'angular-server-side-configuration';

  For programmatic access to configuration or services within your Angular application, `NgsscModule` should be imported and added to your `AppModule` imports. This is configured automatically by `ng add`.
• NgsscService

  import { NgsscService } from 'angular-server-side-configuration';

  While configuration is often directly accessible via `NG_ENV` (if configured by `ng add`), `NgsscService` provides a structured way to access server-side injected configurations within your Angular components or services.

Quickstart

This quickstart demonstrates how to set up server-side configuration, build an Angular application using the custom builder, and then access the injected environment variables within an Angular component.

ng add angular-server-side-configuration

# When prompted 'Would you like to use the experimental builders for build and serve?', answer 'n'.

# Configure an environment variable in your shell (e.g., in a CI/CD pipeline or Dockerfile)
export NG_APP_API_URL="https://api.example.com/production"

# Build your Angular application with the ngssc builder
ng run your-project-name:ngsscbuild:production

# Example app.component.ts to consume the config
import { Component, OnInit } from '@angular/core';
import { NgsscService } from 'angular-server-side-configuration';

@Component({
  selector: 'app-root',
  template: `<h1>API URL: {{ apiUrl }}</h1>`
})
export class AppComponent implements OnInit {
  apiUrl: string | null = null;

  constructor(private ngsscService: NgsscService) {}

  ngOnInit(): void {
    // Access configuration injected by the server-side process
    this.apiUrl = this.ngsscService.get('API_URL');
    console.log('Resolved API URL:', this.apiUrl);
  }
}