The architecture of an initialized Angular CLI project has been changed, mostly under the hood, since the releasing 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 indicate a few changes on purpose to understand what has been improved.

What is an Angular Workspace?

Most likely that we all encounter 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 able to 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:

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:

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️⃣ - defaultCollection

The defaultCollection property 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 in a manner of displaying console warnings due to Angular CLI’s commands. We can disable the “version mismatch” warning in case of version conflicts regarding the global and local Angular CLI version - and for TypeScript versions either.

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.

By default, there is another project alongside our main project - a project with the e2e tests:

In fact - an e2e project is initialized every time an internal application is generated by Angular CLI.

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

1️⃣ - root

The root property specifies what’s the main directory with all project’s files. Probably will be an empty value for the main project of our workspace whereas it indicates for 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

Written in the official Angular style guide that we should adopt 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 the root level and internal project’s level either, the internal project’s level would be applied. As you probably guess, that’s done through the schematics property.

6️⃣ - targets

Any project in a workspace able to 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:

The property serve, for example, is the architect target whereas @angular-devkit/build-angular: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 targets property lets us define targets for a project plus its options for various configurations.

defaultProject

The defaultProject property represents the name which shows up while using some of Angular CLI’s commands.

Conclusions

In this article we explained what’s an Angular Workspace 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 able to consist 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 a link to the sample project we created.