Angular Workspace Configuration

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

Overall 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.

• version: The configuration-file version.
• newProjectRoot: Path where new projects are created. Absolute or relative to the workspace folder.
• defaultProject: Default project name to use in commands, were not provided as an argument. When you use ng new to create a new app in a new workspace, that app is the default project for the workspace until you change it here.
• schematics : A set of schematics that customize the ng generate sub-command option defaults for this workspace.
• projects : Contains a subsection for each project (library, app, e2e test app) in the workspace, with the per-project configuration options.

The initial app that you create with ng new app_name is listed under "projects", along with its corresponding end-to-end test app:

projects
app_name
.......
app_name-e2e
.......

Each additional app that you create with ng generate application has a corresponding end-to-end test project, with its own configuration section. When you create a library project with ng generate the library, the library project is also added to the projects section.

Note that the projects section of the configuration file does not correspond exactly to the workspace file structure.

• The initial app created by ng new is at the top level of the workspace file structure, along with its e2e app.
• Additional apps, e2e apps, and libraries go into a projects folder in the workspace.

Project configuration options

The following top-level configuration properties are available for each project, under projects:<project_name>.

````
"my-v7-app": {
  "root": "",
  "sourceRoot": "src",
  "projectType": "application",
  "prefix": "app",
  "schematics": {},
  "architect": {}
}
````

Generation schematics

Angular generation schematics are instructions for modifying a project by adding files or modifying existing files. Individual schematics for the default Angular CLI ng generate sub-commands are collected in the package @angular. Specify the schematic name for a subcommand in the format schematic-package:schematic-name; for example, the schematic for generating a component is @angular:component.

The JSON schemas for the default schematics used by the CLI to generate projects and parts of projects are collected in the package @schematics/angular. The schema describes the options available to the CLI for each of the ng generate sub-commands, as shown in the --help output.

The fields given in the schema corresponding to the allowed argument values and defaults for the CLI sub-command options. You can update your workspace schema file to set a different default for a sub-command option.

Project tool configuration options

Architect is the tool that the CLI uses to perform complex tasks, such as compilation and test running, according to provided configurations. The architect section of angular.json contains a set of Architect targets. Many of the targets correspond to the CLI commands that run them. Some additional predefined targets can be run 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. In addition, each target has an options section that configures default options for the target, and a configuration section that names and specifies alternative configurations for the target.

````
"architect": {
  "build": { },
  "serve": { },
  "e2e" : { },
  "test": { },
  "lint": { },
  "extract-i18n": { },
  "server": { },
  "app-shell": { }
}
````

• The architect/build section configures defaults for options of the ng build command.
• The architect/serve section overrides build defaults and supplies additional serve defaults for the ng serve command. In addition to the options available for the ng build command, it adds options related to serving the app.
• The architect/e2e section overrides build-option defaults for building end-to-end testing apps using the ng e2e command.
• The architect/test section overrides build-option defaults for test builds and supplies additional test-running defaults for the ng test command.
• The architect/lint section configures defaults for options of the ng lint command, which performs code analysis on project source files. The default linting tool for Angular is TSLint.
• The architect/extract-i18n section configures defaults for options of the ng-xi18n tool used by the ng xi18n command, which extracts marked message strings from source code and outputs translation files.
• The architect/server section configures defaults for creating a Universal app with server-side rendering, using the ng run <project>:server command.
• The architect/app-shell section configures defaults for creating an app shell for a progressive web app (PWA), using the ng run <project>:app-shell command.

In general, the options for which you can configure defaults correspond to the command options listed in the CLI reference page for each command. Note that all options in the configuration file must use camelCase, rather than dash-case.

Build target

The architect/build section configures defaults for options of the ng build command. It has the following top-level properties.

Default build targets

Angular defines default builders for use with the Architect tool and ng run command. The default builders provide implementations that use a particular tool to perform a complex operation.

The JSON schemas that the define the options and defaults for each of these default builders are collected in the @angular-devkit/build-angular package. The schemas configure options for the following Architect build targets:

• app-shell
• browser
• dev-server
• extract-i18n
• karma
• protractor
• server
• tslint

Alternate build configurations

By default, a production configuration is defined, and the ng build command has --prod option that builds using this configuration. The production configuration sets defaults that optimize the app in a number of ways, such bundling files, minimizing excess whitespace, removing comments and dead code, and rewriting code to use short, cryptic names ("minification").

You can define and name additional alternate configurations (such as stage, for instance) appropriate to your development process. Some examples of different build configurations are stable, archive and next used by AIO itself, and the individual locale-specific configurations required for building localized versions of an app. For details, see Internationalization (i18n).

Additional build and test options

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

Some additional options (listed below) can only be set through the configuration file, either by direct editing or with the ng config command.

Project asset configuration

Each build target configuration can include as assets array that lists files or folders you want to copy as-is when building your project. By default, the src/assets/ folder and src/favicon.ico are copied over.

```
"assets": [
  "src/assets",
  "src/favicon.ico"
]
	```
	

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. A asset specification object can have the following fields.

• glob: A node-glob using input as base directory.
• input: A path relative to the workspace root.
• output: A path relative to outDir (default is dist/project-name). Because of the security implications, the CLI never writes files outside of the project output path.
• ignore: A list of globs to exclude.

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

```
"assets": [
  { "glob": "**/*", "input": "src/assets/", "output": "/assets/" },
  { "glob": "favicon.ico", "input": "src/", "output": "/" },
]
```

You can use this extended configuration to copy assets from outside your project. For example, the following configuration copies assets from a node package:

"assets": [
 {"glob":"**/*", "input": "./node_modules/some-package/images", "output": "/some-package/" },
]

The contents of node_modules/some-package/images/ will be available in dist/some-package/.

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

"assets": [
 { "glob": "**/*", "input": "src/assets/", "ignore": ["**/*.svg"], "output": "/assets/" },
]

Previous: Dependency Injection in Action
Next: TypeScript Configuration