Understanding the Angular CLI Workspace File

The architecture of an initialized Angular CLI project has been changed, mostly under the hood, since the release of Angular CLI v6-RC2. As you might have noticed, the old configuration file .angular-cli.json was replaced by a new one:

Let’s go over the main changes to understand what improved.

Update (September 2026): The workspace file has evolved since Angular v6: the targets property is called architect, the default builders come from @angular/build, e2e projects and the TSLint target are no longer generated, defaultProject was removed and defaultCollection was replaced by schematicCollections. The examples below were updated accordingly - check out the workspace configuration reference for the full details.

What is an Angular Workspace?

We’ve most likely all encountered the .angular-cli.json file when generating a project using Angular CLI.

It’s well-known that this file is used as the configuration schema for the whole project and manipulated by the CLI, including managing of different environments, testing, proxy, third-party resources and plenty of built-in tools and capabilities for developing our application.

When it comes to managing multiple applications within a single directory - it’s indeed possible, but not ideal. We cannot share and reuse common code across the multiple applications easily. Beyond that, we cannot configure the build process for each application without the aid of npm scripts.

Both are possible now with the sixth version of Angular CLI! 😍

Let’s define a new term:

An Angular Workspace is a directory which is generated via Angular CLI and can contain multiple projects or libraries that derive the configuration out of a single file.

In practice - the old and familiar output of an Angular CLI project is called an Angular Workspace from now on.

It’s noteworthy that it’s not just a name change but a significant step for refactoring the CLI’s core, which is split up now into several projects, on top of Schematics.

Inside the root of such a workspace, appears a new configuration file called angular.json (instead of .angular-cli.json that’s deprecated):

What we’re going to do now is to go through the new schema and understand it step by step.

Notice that all the practical information is available in the official documentation. However, the purpose of this article is to dive a little deeper into the schema and elaborate as necessary. On top of that, the following explanations are aligned with Angular Workspace schema v1.

Exploring the Workspace File

Let’s generate a new sample workspace by running ng new angular-cli-workspace-example.

This is the initialized configuration file we’re supposed to get:

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "newProjectRoot": "projects",
  "projects": {
    "angular-cli-workspace-example": {
      "root": "",
      "sourceRoot": "src",
      "projectType": "application",
      "prefix": "app",
      "schematics": {},
      "architect": {
        "build": {},
        "serve": {},
        "extract-i18n": {},
        "test": {}
      }
    }
  }
}

Note: The content of architect targets is omitted in order to simplify the example above. The schematics and cli properties aren’t added by default but we’re going to explore them as well.

It’s about time to start explaining that schema! 🕵️

$schema

JSON Schema is a tool that allows us to annotate and validate the structure of JSON data. It’s used by Angular CLI in order to enforce the specification of Angular Workspace schema:

The $schema property refers to the Angular CLI implementation file for JSON Schema.

version

The version property specifies what’s the Angular Workspace schema version which is currently in use.

schematics

Most likely you’ve heard about Schematics, one way or another. In case you haven’t - it’s a workflow tool, as part of Angular DevKit, which lets us transform, generate or update our project development workflow. Just for the record - Angular CLI uses Schematics under the hood in order to perform its job and the truth is that Angular Schematics packages have been derived and created from the CLI’s core.

The schematics property provides us an ability to configure the options of Schematics packages in the root level of our workspace.

Let’s suppose we’d like to guarantee that every component will be created with different default settings. For instance - using “OnPush” as a detection strategy and exporting that component through the declaring module, by default.

That’s how we can make it work:

"schematics": {
  "@schematics/angular:component": {
    "changeDetection": "OnPush",
    "export": true
  }
}

Notice that enforcement will be applied on projects from any level within the workspace.

In case you want to explore additional Schematics packages which have been built for Angular CLI and are possible to be used - check this list out, pick a package and review its schema.json file.

cli

The cli property let us define the configuration for Angular CLI in our workspace.

These are the configurable properties:

1️⃣ - schematicCollections

The schematicCollections property (formerly defaultCollection) specifies what’s the set of Schematics which in use. The @nrwl/schematics set is an excellent example of another Schematics implementation for the sake of development and maintenance of Angular applications - with an emphasis on enterprises.

2️⃣ - packageManager

The packageManager property specifies which package manager Angular CLI uses to perform the commands:

3️⃣ - warnings

The warnings property controls which console warnings of Angular CLI’s commands are displayed. We can disable the "version mismatch" warning in case of version conflicts regarding the global and local Angular CLI version - and for TypeScript versions as well.

newProjectRoot

The newProjectRoot property specifies where’s the place that new internal applications and libraries (as long as these are generated by the CLI) will be placed:

Notice that the default value is projects.

projects

The projects property includes the configuration for any project in our workspace.

Here’s how it looks for our main project:

{
  "projects": {
    "angular-cli-workspace-example": {
      "root": "",
      "sourceRoot": "src",
      "projectType": "application",
      "prefix": "app",
      "schematics": {},
      "architect": {}
    }
  }
}

In the past, an e2e project was initialized every time an internal application was generated by Angular CLI - however, e2e projects are no longer generated.

Each project within our workspace can be configured with the following properties:

1️⃣ - root

The root property specifies what’s the main directory with all project’s files. It’s usually empty for the main project and points to a specific directory for internal projects.

2️⃣ - sourceRoot

The sourceRoot property specifies where the source files are placed for the project.

3️⃣ - projectType

Using ng generate it’s possible now to create internal projects within our main project, which are configured as part of the general configuration file. Those projects could be generated as an internal application or library. That’s exactly the reason for the projectType property - a statement whether that project is an application or library.

4️⃣ - prefix

The official Angular style guide recommends adopting a custom prefix for components and directives in order to identify them completely and prevent collisions. The prefix property specifies that custom prefix which will be applied when generating components or directives using Angular CLI.

5️⃣ - schematics

In a similar way, it’s possible to configure the options of Schematics packages in a level of an internal project, so these will be applied strictly on that project. In case that same option is defined on both the root level and the internal project’s level, the internal project’s level would be applied. As you probably guess, that’s done through the schematics property.

6️⃣ - architect

Any project in a workspace can contain and customize automatic task commands, such as bundling, serving, testing, linting and more. These are based on prebuilt builders and called Architect Targets.

Here’s an example for the targets of our main project:

"angular-cli-workspace-example": {
  "root": "",
  "sourceRoot": "src",
  "projectType": "application",
  "prefix": "app",
  "schematics": {},
  "architect": {
    "build": {
      "builder": "@angular/build:application",
      "options": {},
      "configurations": {}
    },
    "serve": {
      "builder": "@angular/build:dev-server",
      "options": {},
      "configurations": {}
    },
    "extract-i18n": {
      "builder": "@angular/build:extract-i18n",
      "options": {}
    },
    "test": {
      "builder": "@angular/build:unit-test",
      "options": {}
    }
  }
}

The property serve, for example, is the architect target whereas @angular/build:dev-server is the prebuilt Angular builder. On top of that, we can run targets of a specific project directly using ng run, so that serve target is performed by running ng run angular-cli-workspace-example:serve:

The architect property lets us define targets for a project plus its options for various configurations.

Note: The TSLint-based lint target is no longer generated. Linting is added by running ng add @angular-eslint/schematics.

defaultProject

The defaultProject property represented the name which shows up while using some of Angular CLI’s commands. Note: This property was removed in newer versions of Angular CLI.

Wrapping Up

In this article, we explained what an Angular Workspace is and went through the configuration schema for such a workspace (v1).

Let’s recap:

• The .angular-cli.json file has been replaced by angular.json since Angular CLI v6-RC2.
• An Angular Workspace is a project which is produced by the ng new command.
• An Angular Workspace can contain the sources of multiple internal applications and libraries, alongside one configuration file.
• Angular CLI uses JSON Schema to enforce the configuration schema.
• The Angular team created Schematics packages which are used by the CLI.
• We can configure the options of Schematics packages, as we please, for the root project and internal projects as well.
• We can configure Angular CLI to use another set of Schematics and package manager easily.
• The Angular team created prebuilt Angular builders based on the CLI’s core in context of automatic task commands.
• We can use Angular builders in order to attach runnable commands, which are called Architect Targets, to the root project and internal projects as well.
• Architect Targets are customizable in terms of options and various configurations.

Here’s the sample project we created.