Angular workspace configuration

The angular.json file at the root level of an Angular workspace provides workspace-wide and project-specific configuration defaults. These are used for build and development tools provided by the Angular CLI. Path values given in the configuration are relative to the root workspace directory.

General JSON structure

At the top-level of angular.json, a few properties configure the workspace and a projects section contains the remaining per-project configuration options. You can override Angular CLI defaults set at the workspace level through defaults set at the project level. You can also override defaults set at the project level using the command line.

The following properties, at the top-level of the file, configure the workspace.

The initial application that you create with ng new app-name is listed under "projects":

When you create a library project with ng generate library, the library project is also added to the projects section.

HELPFUL: The projects section of the configuration file does not correspond exactly to the workspace file structure.

• The initial application created by ng new is at the top level of the workspace file structure.
• Other applications and libraries are under the projects directory by default.

For more information, see Workspace and project file structure.

Angular CLI configuration options

The following properties are a set of options that customize the Angular CLI.

Cache options

_ ci enables caching only in continuous integration (CI) environments. _ local enables caching only outside of CI environments. * all enables caching everywhere. | local | ci | all | local | | path | The directory used to stored cache results. | string | .angular/cache |

Warnings options

Project configuration options

The following top-level configuration properties are available for each project, under projects['project-name'].

Schematics

Angular schematics are instructions for modifying a project by adding new files or modifying existing files. These can be configured by mapping the schematic name to a set of default options.

The "name" of a schematic is in the format: <schematic-package>:<schematic-name>. Schematics for the default Angular CLI ng generate sub-commands are collected in the package @schematics/angular. For example, the schematic for generating a component with ng generate component is @schematics/angular:component.

The fields given in the schematic's schema correspond to the allowed command-line argument values and defaults for the Angular CLI sub-command options. You can update your workspace schema file to set a different default for a sub-command option. For example, to disable standalone in ng generate component by default:

{
  "projects": {
    "my-app": {
      "schematics": {
        "@schematics/angular:component": {
          "standalone": false
        }
      }
    }
  }
}

Configuring CLI builders

Architect is the tool that the Angular CLI uses to perform complex tasks, such as compilation and test running. Architect is a shell that runs a specified builder to perform a given task, according to a target configuration. You can define and configure new builders and targets to extend the Angular CLI. See Angular CLI Builders.

Default Architect builders and targets

Angular defines default builders for use with specific commands, or with the general ng run command. The JSON schemas that define the options and defaults for each of these builders are collected in the @angular-devkit/build-angular package. The schemas configure options for the following builders.

Configuring builder targets

The architect section of angular.json contains a set of Architect targets. Many of the targets correspond to the Angular CLI commands that run them. Other targets can be executed using the ng run command, and you can define your own targets.

Each target object specifies the builder for that target, which is the npm package for the tool that Architect runs. Each target also has an options section that configures default options for the target, and a configurations section that names and specifies alternative configurations for the target. See the example in Build target below.

HELPFUL: All options in the configuration file must use camelCase, rather than dash-case as used on the command line.

Build target

Each target under architect has the following properties:

For example, to configure a build with optimizations disabled:

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "optimization": false
          }
        }
      }
    }
  }
}

Alternate build configurations

Angular CLI comes with two build configurations: production and development. By default, the ng build command uses the production configuration, which applies several build optimizations, including:

• Bundling files
• Minimizing excess whitespace
• Removing comments and dead code
• Minifying code to use short, mangled names

You can define and name extra alternate configurations (such as staging, for instance) appropriate to your development process. You can select an alternate configuration by passing its name to the --configuration command line flag.

For example, to configure a build where optimization is enabled only for production builds (ng build --configuration production):

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "optimization": false
          },
          "configurations": {
            "production": {
              "optimization": true
            }
          }
        }
      }
    }
  }
}

You can also pass in more than one configuration name as a comma-separated list. For example, to apply both staging and french build configurations, use the command ng build --configuration staging,french. In this case, the command parses the named configurations from left to right. If multiple configurations change the same setting, the last-set value is the final one. In this example, if both staging and french configurations set the output path, the value in french would get used.

Extra build and test options

The configurable options for a default or targeted build generally correspond to the options available for the ng build, and ng test commands. For details of those options and their possible values, see the Angular CLI Reference.

Extra serve options

The dev-server comes with its own set of options that generaly correspond to the options available for the ng serve command.

Complex configuration values

The assets, index, outputPath, styles, and scripts options can have either simple path string values, or object values with specific fields. The sourceMap and optimization options can be set to a simple boolean value. They can also be given a complex value using the configuration file.

The following sections provide more details of how these complex values are used in each case.

Assets configuration

Each build target configuration can include an assets array that lists files or folders you want to copy as-is when building your project. By default, the contents of the public/ directory are copied over.

To exclude an asset, you can remove it from the assets configuration.

You can further configure assets to be copied by specifying assets as objects, rather than as simple paths relative to the workspace root. An asset specification object can have the following fields.

For example, the default asset paths can be represented in more detail using the following objects.

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "assets": [
              {
                "glob": "**/*",
                "input": "src/assets/",
                "output": "/assets/"
              },
              {
                "glob": "favicon.ico",
                "input": "src/",
                "output": "/"
              }
            ]
          }
        }
      }
    }
  }
}

The following example uses the ignore field to exclude certain files in the assets directory from being copied into the build:

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "assets": [
              {
                "glob": "**/*",
                "input": "src/assets/",
                "ignore": ["**/*.svg"],
                "output": "/assets/"
              }
            ]
          }
        }
      }
    }
  }
}

Styles and scripts configuration

An array entry for the styles and scripts options can be a simple path string, or an object that points to an extra entry-point file. The associated builder loads that file and its dependencies as a separate bundle during the build. With a configuration object, you have the option of naming the bundle for the entry point, using a bundleName field.

The bundle is injected by default, but you can set inject to false to exclude the bundle from injection. For example, the following object values create and name a bundle that contains styles and scripts, and excludes it from injection:

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "styles": [
              {
                "input": "src/external-module/styles.scss",
                "inject": false,
                "bundleName": "external-module"
              }
            ],
            "scripts": [
              {
                "input": "src/external-module/main.js",
                "inject": false,
                "bundleName": "external-module"
              }
            ]
          }
        }
      }
    }
  }
}

Style preprocessor options

In Sass, you can make use of the includePaths feature for both component and global styles. This allows you to add extra base paths that are checked for imports.

To add paths, use the stylePreprocessorOptions option:

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "stylePreprocessorOptions": {
              "includePaths": ["src/style-paths"]
            }
          }
        }
      }
    }
  }
}

Files in that directory, such as src/style-paths/_variables.scss, can be imported from anywhere in your project without the need for a relative path:

// src/app/app.scss
// A relative path works
@import '../style-paths/variables';

// But now this works as well
@import 'variables';

HELPFUL: You also need to add any styles or scripts to the test builder if you need them for unit tests. See also Using runtime-global libraries inside your application.

Optimization configuration

The optimization option can be either a boolean or an object for more fine-tune configuration. This option enables various optimizations of the build output, including:

• Minification of scripts and styles
• Tree-shaking
• Dead-code elimination
• Inlining of critical CSS
• Fonts inlining

Several options can be used to fine-tune the optimization of an application.

Styles optimization options

Fonts optimization options

You can supply a value such as the following to apply optimization to one or the other:

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "stylePreprocessorOptions": {
              "includePaths": ["src/style-paths"]
            }
          }
        }
      }
    }
  }
}

Source map configuration

The sourceMap builder option can be either a boolean or an object for more fine-tune configuration to control the source maps of an application.

The example below shows how to toggle one or more values to configure the source map outputs:

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "sourceMap": {
              "scripts": true,
              "styles": false,
              "hidden": true,
              "vendor": true
            }
          }
        }
      }
    }
  }
}

HELPFUL: When using hidden source maps, source maps are not referenced in the bundle. These are useful if you only want source maps to map stack traces in error reporting tools without showing up in browser developer tools. Note that even though hidden prevents the source map from being linked in the output bundle, your deployment process must take care not to serve the generated sourcemaps in production, or else the information is still leaked.

Source maps without sources content

You can generate source maps without the sourcesContent field, which contains the original source code. This allows you to deploy source maps to production for better error reporting with original source names while protecting your source code from exposure.

To exclude sources content from source maps, set the sourcesContent option to false:

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "sourceMap": {
              "scripts": true,
              "styles": true,
              "sourcesContent": false
            }
          }
        }
      }
    }
  }
}

Index configuration

Configures generation of the application's HTML index.

The index option can be either a string or an object for more fine-tune configuration.

When supplying the value as a string the filename of the specified path will be used for the generated file and will be created in the root of the application's configured output path.

Index options

Output path configuration

The outputPath option can be either a String which will be used as the base value or an Object for more fine-tune configuration.

Several options can be used to fine-tune the output structure of an application.