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
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 property refers to the Angular CLI implementation file for JSON Schema.
version property specifies what’s the Angular Workspace schema version which is currently in use.
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.
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
cli property let us define the configuration for Angular CLI in our workspace.
These are the configurable properties:
1️⃣ - defaultCollection
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
packageManager property specifies which package manager Angular CLI uses to perform the commands:
3️⃣ - warnings
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.
Notice that the default value is
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
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
sourceRoot property specifies where the source files are placed for the project.
3️⃣ - projectType
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
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
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:
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:
targets property lets us define targets for a project plus its options for various configurations.
defaultProject property represents the name which shows up while using some of Angular CLI’s commands.
In this article we explained what’s an Angular Workspace and went through the configuration schema for such a workspace (v1).
.angular-cli.jsonfile has been replaced by
angular.jsonsince Angular CLI v6-RC2.
- An Angular Workspace is a project which is produced by the
- 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.