{"id":15297,"library":"angular-server-side-configuration","title":"Angular Server-Side Configuration","description":"angular-server-side-configuration is an Angular CLI builder and native command-line interface tool designed to enable runtime configuration of Angular applications on the server or within Docker containers using environment variables. This addresses the limitation of Angular CLI's default build-time configuration, providing flexibility in Continuous Delivery environments. It works by searching for environment variable usages at build time and then, via a native CLI, inserting these populated variables into the `index.html` file (or replacing a `<!--CONFIG-->` placeholder) on the host serving the bundled Angular files. The current stable version is 21.0.3, with releases generally aligning with major Angular versions, introducing breaking changes primarily for Angular version upgrades and builder refactoring. Its key differentiator is the separation of build-time processing from deployment-time configuration injection, making it suitable for containerized deployments.","status":"active","version":"21.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/kyubisation/angular-server-side-configuration","tags":["javascript","angular","configuration","server","server-side","docker","openshift","kubernetes","typescript"],"install":[{"cmd":"npm install angular-server-side-configuration","lang":"bash","label":"npm"},{"cmd":"yarn add angular-server-side-configuration","lang":"bash","label":"yarn"},{"cmd":"pnpm add angular-server-side-configuration","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Angular applications.","package":"@angular/core","optional":false}],"imports":[{"note":"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.","symbol":"ngssc","correct":"ng add angular-server-side-configuration"},{"note":"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`.","wrong":"import NgsscModule from 'angular-server-side-configuration';","symbol":"NgsscModule","correct":"import { NgsscModule } from 'angular-server-side-configuration';"},{"note":"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.","symbol":"NgsscService","correct":"import { NgsscService } from 'angular-server-side-configuration';"}],"quickstart":{"code":"ng add angular-server-side-configuration\n\n# When prompted 'Would you like to use the experimental builders for build and serve?', answer 'n'.\n\n# Configure an environment variable in your shell (e.g., in a CI/CD pipeline or Dockerfile)\nexport NG_APP_API_URL=\"https://api.example.com/production\"\n\n# Build your Angular application with the ngssc builder\nng run your-project-name:ngsscbuild:production\n\n# Example app.component.ts to consume the config\nimport { Component, OnInit } from '@angular/core';\nimport { NgsscService } from 'angular-server-side-configuration';\n\n@Component({\n  selector: 'app-root',\n  template: `<h1>API URL: {{ apiUrl }}</h1>`\n})\nexport class AppComponent implements OnInit {\n  apiUrl: string | null = null;\n\n  constructor(private ngsscService: NgsscService) {}\n\n  ngOnInit(): void {\n    // Access configuration injected by the server-side process\n    this.apiUrl = this.ngsscService.get('API_URL');\n    console.log('Resolved API URL:', this.apiUrl);\n  }\n}\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=20.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=19.0.0"},{"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).","message":"Angular CLI compiler became stricter with global typings in v19, leading to 'Cannot find name 'process'' errors when accessing `process.env` directly.","severity":"gotcha","affected_versions":">=19.0.0"},{"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.","message":"The default `searchPattern` for environment variables changed in v16 to `{sourceRoot}/**/environments/environment*.ts` for improved security and to follow 'Secure by default' principles.","severity":"breaking","affected_versions":">=16.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=15.0.0 <15.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","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.","error":"TS2304: Cannot find name 'process'."},{"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.","cause":"Attempting to use the experimental Angular CLI builders (`angular-server-side-configuration:build` or `:serve`) which were removed in version 20.0.0.","error":"Error: The 'build' and 'dev-server' experimental builders have been removed."},{"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.","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.","error":"Environment variable 'YOUR_VAR' is undefined when accessed via `NgsscService`."}],"ecosystem":"npm"}