Registry /
devops / angular-server-side-configuration
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✓ import { NgsscModule } from 'angular-server-side-configuration';
✗ 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.
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);
}
}
angular-server-side-configuration --version
Debug
Known issues
breakingUpgrading to v20 requires an upgrade to Angular 20. Additionally, the experimental build and dev-server builders introduced in earlier versions have been completely removed.fixEnsure 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.
affects: >=20.0.0
breakingWith 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.fixUpdate your deployment scripts or Dockerfiles to use the standard 64-bit binaries. The deprecation notice for these binaries was issued in v18.1.0.
affects: >=19.0.0
gotchaAngular CLI compiler became stricter with global typings in v19, leading to 'Cannot find name 'process'' errors when accessing `process.env` directly.fixAdd `"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).
affects: >=19.0.0
breakingThe default `searchPattern` for environment variables changed in v16 to `{sourceRoot}/**/environments/environment*.ts` for improved security and to follow 'Secure by default' principles.fixIf 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.
affects: >=16.0.0
gotchaWith 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.fixRemove 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.
affects: >=15.0.0 <15.1.0
Errors
Common errors & fixes
TS2304: Cannot find name 'process'.
The Angular CLI compiler became stricter with global typings for `process` in Angular v19, leading to this error when `process.env` is accessed directly.
fixAdd `"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.
Attempting to use the experimental Angular CLI builders (`angular-server-side-configuration:build` or `:serve`) which were removed in version 20.0.0.
fixUpdate 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`.
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.
fixEnsure 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.
Audit
Dependencies
@angular/corerequiredPeer dependency for Angular applications.