In an Angular CLI project, how do you add a staging build configuration with its own environment file, and what does fileReplacements do?
answer
- one file imported, another compiled
- generate the environments folder
- a named configuration per stage
- serve needs its own entry
- values end up in the bundle
basics
~10 sAdd a staging entry under the Angular CLI build target's configurations whose fileReplacements swaps src/environments/environment.ts for environment.staging.ts at compile time, give serve a matching buildTarget, and build with ng build -c staging.
solid answer
~40 sRun `ng generate environments` once: it creates `src/environments/environment.ts`, used by the default `production` configuration, plus `environment.development.ts` with a matching `fileReplacements` entry in the `development` configuration. For staging, add `environment.staging.ts` exporting the same shape and a `staging` configuration under the `build` target with `"fileReplacements": [{ "replace": "src/environments/environment.ts", "with": "src/environments/environment.staging.ts" }]`. Application code always imports the original `environment.ts`; during a staging build the compiler loads the staging file in its place, so the values are baked into the bundle at build time. Add a `staging` entry under `serve` with `"buildTarget": "my-app:build:staging"` if you want `ng serve -c staging`. Remember that a configuration you select explicitly replaces the default one, so production-only settings such as budgets and hashing must be repeated or layered with `-c production,staging`.
code
json · 29 lines{
"projects": {
"my-app": {
"architect": {
"build": {
"builder": "@angular/build:application",
"defaultConfiguration": "production",
"configurations": {
"staging": {
"outputHashing": "all",
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.staging.ts"
}
]
}
}
},
"serve": {
"builder": "@angular/build:dev-server",
"configurations": {
"staging": { "buildTarget": "my-app:build:staging" }
}
}
}
}
}
}go deeper
Recall that environment files hold per-environment values, that code imports environment.ts, and that ng build -c staging selects the staging configuration.
Explain how fileReplacements swaps files at compile time, what ng generate environments creates, and why serve needs its own staging entry with a buildTarget.
Catch the configuration-selection trap, where staging loses production's budgets and hashing, and decide between repeating options and layering configurations.
Weigh build-per-environment files against runtime configuration when one artifact must move through several stages.
## The goal A team needs a third build, **staging**, that talks to the staging API and enables a debug banner, while `production` and `development` keep their own values. The Angular CLI solves this with two pieces of `angular.json`: a **named configuration** and **`fileReplacements`**. ## Step 1: create the environment files ```bash ng generate environments ``` The schematic, which only works on application projects with a `build` target: - creates `src/environments/environment.ts`, the file used by the **default** configuration (normally `production`); - for every other build configuration, such as `development`, creates `environment.<name>.ts` and adds a `fileReplacements` entry to that configuration; - skips files and entries that already exist, so it is safe to run again after adding a configuration. The generated files contain only `export const environment = {};`; you add the properties. ```ts // src/environments/environment.ts (production values) export const environment = { apiUrl: 'https://api.example.com', showDebugBanner: false }; // src/environments/environment.staging.ts export const environment = { apiUrl: 'https://staging-api.example.com', showDebugBanner: true }; ``` ## Step 2: add the staging configuration ```json "build": { "builder": "@angular/build:application", "defaultConfiguration": "production", "configurations": { "production": { "budgets": [ ... ], "outputHashing": "all" }, "development": { ... }, "staging": { "outputHashing": "all", "fileReplacements": [ { "replace": "src/environments/environment.ts", "with": "src/environments/environment.staging.ts" } ] } } } ``` Then build it with `ng build --configuration staging`. ## Step 3: let serve use it too `ng serve -c staging` looks up a `staging` configuration on the **serve** target, not the build target. Add one: ```json "serve": { "configurations": { "staging": { "buildTarget": "my-app:build:staging" } } } ``` Without it the CLI stops with an error saying that configuration `staging` is not set for target `serve`. ## What fileReplacements actually does - It maps one source path to another **inside the compilation**. When the compiler loads `src/environments/environment.ts`, it reads `environment.staging.ts` instead. - Paths are relative to the **workspace root**. If the `with` file does not exist, the build fails immediately. - In the application builder, both paths must be script or JSON files (`.ts`, `.js`, `.mjs`, `.tsx`, `.json` and similar); stylesheets and templates cannot be swapped this way. - Code must import the **original** path. A component that imports `environment.staging.ts` directly gets staging values in every build. - The replacement happens at **build time**. The values end up in the JavaScript bundle, readable by anyone who loads the page, so the files must never hold secrets. ## The trap: selected configurations do not stack on the default `defaultConfiguration` is used **only when no configuration is named**. `ng build -c staging` therefore applies `options` plus `staging`, and **not** `production`. Anything production added, such as `budgets` and `outputHashing: "all"`, is missing unless staging repeats it or you layer both: ```bash ng build -c production,staging ``` Configurations listed with commas are applied left to right, and a later configuration replaces a whole option set by an earlier one, so the staging `fileReplacements` array replaces production's rather than merging with it. ## Common mistakes - **Putting `fileReplacements` under `options`** instead of under `configurations.staging`: every configuration, production included, then compiles the staging file. - **Importing the replacement file directly**, which bypasses the swap for that import. - **Forgetting the serve entry**, then assuming `ng serve -c staging` is broken. - **Diverging shapes**: if `environment.staging.ts` lacks a property that `environment.ts` has, the problem only surfaces when the staging configuration is built. Keep every environment file exporting the same shape, for example by typing them against a shared interface. - **Treating the files as runtime configuration**: changing `environment.staging.ts` after the build changes nothing until the next build. ## Summary of the pieces | Piece | Where | Purpose | |---|---|---| | `environment.ts` | `src/environments/` | default values, imported by the code | | `environment.staging.ts` | `src/environments/` | staging values | | `configurations.staging.fileReplacements` | build target | swaps the file at compile time | | `configurations.staging.buildTarget` | serve target | lets `ng serve -c staging` compile it |
- What happens if a component imports environment.staging.ts directly?It bypasses the replacement: `fileReplacements` only intercepts loads of the `replace` path, so that component gets staging values in every build, production included. All code must import the original `environment.ts` and let the configuration decide what is compiled.
- Can one production bundle be promoted to staging if the API URL comes from fileReplacements?No. The replacement happens at build time, so each configuration produces a different bundle with its values inlined. Promoting one artifact through stages needs configuration loaded at runtime instead, which is a different design from environment files.
- Is it safe to put an API key in environment.staging.ts?No. Environment files are compiled into the client bundle and are readable by anyone who loads the page. Secrets belong on a server, behind a proxy or a backend endpoint, never in `src/environments/`.
fileReplacements works like a stage manager swapping the prop on the table before the curtain rises: the actors always reach for the same spot, and which object they pick up depends on which show is being staged tonight.
saying these in an interview costs you the question
- Components should import environment.staging.ts directly in staging code paths.
- fileReplacements swaps files at runtime depending on the host name.
- ng build -c staging also applies the production configuration's settings.
- Adding a staging build configuration makes ng serve -c staging work automatically.
- Environment files are a safe place for API keys because they are not public.