Welcome to Blogs Overflow: Empowering Knowledge by Overflow Orbits Private Limited. Comprehensive Guide to Configuring angular.json in Angular Projects – The angular.json
file is a crucial configuration file for Angular projects. It defines the structure and settings for the project, including build and development configurations. This guide will walk you through each key in the angular.json
file, explaining its purpose, when to use it, and the best settings for both production and non-production environments.
Top-Level Keys
$schema
- Purpose: Defines the schema for the
angular.json
file for validation and IntelliSense support. - When to Use: Always present.
- Example:
"$schema": "https://json.schemastore.org/angular-cli.json"
version
- Purpose: Specifies the version of the configuration file format.
- When to Use: Always present.
- Example:
"version": 1
projects
- Purpose: Contains configurations for each project in the workspace.
- When to Use: Always present, with each Angular project listed as a key.
- Example:
"projects": {
"my-app": { ... },
"my-library": { ... }
}
projects
Key
Each project in the projects
object has its own set of configurations:
projectType
- Purpose: Defines the type of project (
application
orlibrary
). - When to Use: Always present.
- Example:
"projectType": "application"
root
- Purpose: The root directory for the project.
- When to Use: Always present.
- Example:
"root": ""
sourceRoot
- Purpose: The root directory for source files.
- When to Use: Always present.
- Example:
"sourceRoot": "src"
prefix
- Purpose: Prefix to apply to generated selectors.
- When to Use: Always present.
- Example:
"prefix": "app"
architect
- Purpose: Defines build configurations and other architect targets like serve, test, lint, etc.
- When to Use: Always present.
- Example:
"architect": {
"build": { ... },
"serve": { ... },
"test": { ... },
"lint": { ... }
}
architect
Key
The architect
key contains configurations for different build targets. Common targets include build
, serve
, test
, and lint
.
Build Target Configuration (build
)
builder
- Purpose: Specifies the builder to use for this target. For building browser applications, use
@angular-devkit/build-angular:browser
. - When to Use: Always present.
- Example:
"builder": "@angular-devkit/build-angular:browser"
options
- Purpose: Configuration options specific to the build target.
- When to Use: Always present.
- Example:
"options": {
"outputPath": "dist/my-app",
"index": "src/index.html",
"main": "src/main.ts",
"polyfills": "src/polyfills.ts",
"tsConfig": "tsconfig.app.json",
"assets": ["src/favicon.ico", "src/assets"],
"styles": ["src/styles.css"],
"scripts": []
}
configurations
- Purpose: Named alternative configurations (e.g.,
production
,development
). - When to Use: When different settings are needed for different environments.
- Example:
"configurations": {
"production": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.prod.ts"
}
],
"optimization": true,
"outputHashing": "all",
"sourceMap": false,
"extractCss": true,
"namedChunks": false,
"aot": true,
"extractLicenses": true,
"vendorChunk": false,
"buildOptimizer": true,
"budgets": [
{
"type": "initial",
"maximumWarning": "2mb",
"maximumError": "5mb"
}
]
}
}
Best Settings for Production and Non-Production
Production
optimization
:true
to enable optimization (minification and dead code elimination).outputHashing
:"all"
to enable output hashing for all files, useful for cache busting.sourceMap
:false
to disable source maps, reducing bundle size.extractCss
:true
to extract CSS into separate files.namedChunks
:false
to minimize the naming of chunks.aot
:true
to enable Ahead-of-Time (AOT) compilation.extractLicenses
:true
to extract licenses into a separate file.vendorChunk
:false
to minimize vendor chunk.buildOptimizer
:true
to enable Angular’s build optimizer.
Example:
"production": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.prod.ts"
}
],
"optimization": true,
"outputHashing": "all",
"sourceMap": false,
"extractCss": true,
"namedChunks": false,
"aot": true,
"extractLicenses": true,
"vendorChunk": false,
"buildOptimizer": true,
"budgets": [
{
"type": "initial",
"maximumWarning": "2mb",
"maximumError": "5mb"
}
]
}
Non-Production
optimization
:false
to speed up build times.outputHashing
:none
to disable output hashing.sourceMap
:true
to enable source maps for easier debugging.extractCss
:false
to keep CSS in the JavaScript bundle.namedChunks
:true
for easier identification of chunks.aot
:false
to use Just-in-Time (JIT) compilation.extractLicenses
:false
to keep licenses within the bundles.vendorChunk
:true
to separate vendor libraries.
Example:
"development": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.dev.ts"
}
],
"optimization": false,
"outputHashing": "none",
"sourceMap": true,
"extractCss": false,
"namedChunks": true,
"aot": false,
"extractLicenses": false,
"vendorChunk": true
}
Serve Target Configuration (serve
)
builder
- Purpose: Specifies the builder for serving the application, typically
@angular-devkit/build-angular:dev-server
. - When to Use: Always present.
- Example:
"builder": "@angular-devkit/build-angular:dev-server"
options
- Purpose: Configuration options for serving the application.
- When to Use: Always present.
- Example:
"options": {
"browserTarget": "my-app:build"
}
configurations
- Purpose: Named configurations for serving, often linking to build configurations.
- When to Use: When different settings are needed for different environments.
- Example:
"configurations": {
"production": {
"browserTarget": "my-app:build:production"
}
}
Test Target Configuration (test
)
builder
- Purpose: Specifies the builder for running tests, typically
@angular-devkit/build-angular:karma
. - When to Use: Always present.
- Example:
"builder": "@angular-devkit/build-angular:karma"
options
- Purpose: Configuration options for running tests.
- When to Use: Always present.
- Example:
"options": {
"main": "src/test.ts",
"polyfills": "src/polyfills.ts",
"tsConfig": "tsconfig.spec.json",
"karmaConfig": "karma.conf.js",
"assets": ["src/favicon.ico", "src/assets"],
"styles": ["src/styles.css"],
"scripts": []
}
Lint Target Configuration (lint
)
builder
- Purpose: Specifies the builder for linting, typically
@angular-devkit/build-angular:tslint
. - When to Use: Always present.
- Example:
"builder": "@angular-devkit/build-angular:tslint"
options
- Purpose: Configuration options for linting.
- When to Use: Always present.
- Example:
"options": {
"tsConfig": ["tsconfig.app.json", "tsconfig.spec.json"],
"exclude": ["**/node_modules/**"]
}
Example Project Configuration
Here’s a comprehensive example for an application project in angular.json
:
{
"$schema": "https://json.schemastore.org/angular-cli.json",
"version": 1,
"projects": {
"my-app": {
"projectType": "application",
"root": "",
"sourceRoot": "src",
"prefix": "app",
"architect": {
"build": {
"builder": "@angular-devkit/build-angular:browser",
"options": {
"outputPath": "dist/my-app",
"index": "src/index.html",
"main": "src/main.ts",
"polyfills": "src/polyfills.ts",
"tsConfig": "tsconfig.app.json",
"assets": ["src/favicon.ico", "src/assets"],
"styles": ["src/styles.css"],
"scripts": []
},
"configurations": {
"production": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.prod.ts"
}
],
"optimization": true,
"outputHashing": "all",
"sourceMap": false,
"extractCss": true,
"namedChunks": false,
"aot": true,
"extractLicenses": true,
"vendorChunk": false,
"buildOptimizer": true,
"budgets": [
{
"type": "initial",
"maximumWarning": "2mb",
"maximumError": "5mb"
}
]
},
"development": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.dev.ts"
}
],
"optimization": false,
"outputHashing": "none",
"sourceMap": true,
"extractCss": false,
"namedChunks": true,
"aot": false,
"extractLicenses": false,
"vendorChunk": true
}
}
},
"serve": {
"builder": "@angular-devkit/build-angular:dev-server",
"options": {
"browserTarget": "my-app:build"
},
"configurations": {
"production": {
"browserTarget": "my-app:build:production"
}
}
},
"test": {
"builder": "@angular-devkit/build-angular:karma",
"options": {
"main": "src/test.ts",
"polyfills": "src/polyfills.ts",
"tsConfig": "tsconfig.spec.json",
"karmaConfig": "karma.conf.js",
"assets": ["src/favicon.ico", "src/assets"],
"styles": ["src/styles.css"],
"scripts": []
}
},
"lint": {
"builder": "@angular-devkit/build-angular:tslint",
"options": {
"tsConfig": ["tsconfig.app.json", "tsconfig.spec.json"],
"exclude": ["**/node_modules/**"]
}
}
}
}
}
}
This example covers the basic structure and essential configurations for different targets in an Angular project, providing a solid foundation for both development and production environments.
I hope this guide helps you in understanding and configuring your angular.json
file effectively for your Angular projects.