Angular's angular.json: Your Workspace Blueprint

Why it exists

To provide a single, centralized file for managing the configuration of a workspace that might contain multiple applications and libraries. Without it, every tool and command would need separate configuration, leading to duplication and inconsistency across the project.

The mental model

angular.json is the command center for the Angular CLI. It's a hierarchical configuration file where workspace-wide settings form the base, project-specific settings can override them, and command-line flags provide the final override. This cascade allows for both broad consistency and fine-grained control.

How it works

The file's top level has properties like version and newProjectRoot. The most important section is projects, which contains an object for each application or library. Each project object defines its type (application or library), source code location (sourceRoot), and, crucially, an architect section. The architect section defines "targets" like build, serve, and test, specifying the builder to use and its options. For example, the build target configures the entire build process, from entry points to output paths and optimizations.

When to use it

Use it when adding a new library, configuring different build environments (like staging vs. production), changing the default code generation prefix from 'app' to something more specific, or enabling CLI features like build caching (cli.cache) for faster development cycles.

When not to use it

Do not use angular.json for application-level runtime configuration, like API keys or feature flags. That belongs in environment files (e.g., environment.ts). Also, avoid manually editing the architect section unless you understand builders; the CLI manages most of this for you when you run commands like ng add.

One canonical example

A common task is setting up a production build. Inside projects.my-app.architect.build.configurations, you'll find a production object. Here, you can set optimization: true, outputHashing: 'all', and fileReplacements to swap environment.ts with environment.prod.ts. The CLI uses this configuration automatically when you run ng build --configuration production.