How to Create A Custom Angular CLI Schematic with Nx Tool

TL;DR In this tutorial, we’re going to learn the basics of Nrwl’s tool Nx, as well as how to create a custom workspace CLI schematic. You can see the finished code in this repository.

Note: This tutorial assumes some basic knowledge of Angular and the Angular CLI. If you've never touched Angular before, check out our Real World Angular series.

Concerns of Enterprise Teams

Developing applications on a large enterprise team is different than developing alone or on a small team. While small groups might be able to get away with ad hoc decisions on application structure or coding best practices, the same cannot be said when you’re working with dozens or perhaps hundreds of other people. In addition, enterprise teams need to assume that their code will stick around for many years to come. This means they’ll need to do as much work as possible at the beginning of an application’s development to minimize the cost of maintenance down the road.

We can summarize the concerns of enterprise teams like this:

Consistency — how do we make sure everyone in the organization (which may be thousands of people) follows the same best practices for structuring and writing code?
Safety — how do we ensure that our code will not be subject to attacks or prone to errors?
Increased size and complexity — how can we structure our code so that it can grow without sacrificing clarity or performance?
Changing requirements — how can we keep up with the demands of the business to continually update the application without letting technical debt get out of control?

While small teams and small organizations share these same concerns to some extent, the risks can be catastrophic at the enterprise scale. To learn more about the problems large teams face, check out Victor Savkin’s excellent ng-conf 2018 talk Angular at Large Organizations.

Nx: The Enterprise Toolkit for Angular

Source

Nx is a set of tools for the Angular CLI built by the consulting firm Nrwl to help with exactly these issues of consistency, safety, and maintainability. In addition to including a schematic to implement monorepo-style development of applications and libraries, Nx includes a set of libraries, linters, and code generators to help large teams create and enforce best practices across their organizations.

“Nx by @nrwl_io is a set of tools to help enterprise @angular devs with consistency, safety, and maintainability.”
Tweet This

Out of the box, Nx contains tools to help with:

State management and NgRx
Data persistence
Code linting and formatting
Migrating from AngularJS to Angular
Analyzing dependencies visually
Creating and running better tests
Creating workspace-specific schematics

While we can’t delve into every feature of Nx, we are going to take a look in just a bit at that last one: workspace-specific schematics. Before we do that, though, let’s learn how to get started with Nx.

Nx Basics

Let’s learn the basics of getting up and running with Nx. We’ll need to know how to install Nx, how to generate a workspace, and how to create applications and libraries.

Install Nx

We’ll start by installing Nx, which is really just a collection of Angular CLI schematics. You’ll need Node 8.9 or greater and NPM 5.5.1 or greater for this, which you can install from the Node website.

First, make sure you have the latest version of the Angular CLI installed globally:

npm i -g @angular/cli

(Note that

npm i -g

is just shorthand for

npm install --global

Then, install Nx globally:

npm i -g @nrwl/schematics

Installing Nx globally is actually only required to create workspaces from scratch from the command line. If you’re unable to install things globally at work, don’t worry. You can add Nx capabilities to an existing CLI project by running this command:

ng add @nrwl/schematics

Note: You can also use Angular Console instead of the CLI throughout this tutorial if you'd prefer to work with a GUI instead of the command line.

Create a Workspace

Now that we’ve got Nx installed, we’re ready to create our first workspace. What exactly is a workspace, though? A workspace is an example of a monorepo (short for monorepository) — a repository that holds several related applications and libraries.

Let’s imagine we’ve been tasked to create a pet adoption system. Let’s think about some of the different pieces we might need for this:

A front end application for potential adopters to browse through the pets
A front end application for administrators to update available pets and receive inquiries
Shared UI components between the front ends
Shared data access libraries between the front ends
A Node server to serve up the pet and adoption inquiry data

While we could keep each of these in a separate repository, it would get messy keeping all of the versions in sync, managing dependencies, and ensuring that all developers working on the project have the correct access they need. Monorepos solve these problems and more.

With Nx, a workspace is a monorepo structure for the Angular CLI to keep your applications and libraries organized.

After installing Nx globally, we can run this command:

create-nx-workspace pet-adoption-system

When we run this command with version 7 or later of the CLI and Nx, we'll get two prompted questions. The first is whether we’d like to use a separate name for npm scope, which lets us import internally using a shorthand. For example, we could set the scope to "adoption-suite", which would mean our imports would start with

@adoption-suite

. We’re not going to do this in this tutorial, so we can just hit enter to leave it as the default, which is

pet-adoption-system

The second prompt is whether we’d like to use npm or Yarn for package management. I’ll be using npm in this tutorial, but you’re welcome to use Yarn instead.

This will create a new CLI workspace that will look a bit different from what you’re used to. Instead of the usual

src

folder, you’ll see folders named

apps

libs

, and

tools

at the root of the project. You’ll also see some extra files like

nx.json

to configure Nx,

.prettierrc

to configure the Prettier formatting extension, and

.editorconfig

to set some editor presets. Nx does a lot of set-up for you so you can focus on writing code instead of on tooling.

Create an Application

Let’s create an application in our new workspace and add routing to it.

ng generate app adoption-ui --routing

Version 7 of Nx adds prompts regarding directory placement, style extension, and choice of unit and end-to-end test runners. This is great because we can now easily set up an application using SCSS, Jest for unit testing, and Cypress for end-to-end testing with zero extra work. In this tutorial, feel free to leave all the prompts at their defaults. We won’t be using them here.

Nx’s

app

schematic is almost identical to the built-in CLI version, but it does have a couple of differences. For example, the

routing

option we added configures the root

NgModule

with routing instead of creating a separate module. This has increasingly become best practice in the Angular community to avoid "module pollution," so it’s really nice Nx does this for us by default.

After we’ve run the command, we’ll now have an

apps/adoption-ui

folder with the familiar CLI structure inside of it. Notice that the

AppModule

is set up with routing and that there is a separate

apps/adoption-ui-e2e

folder for Protractor. This differs a bit from the regular CLI setup, where the

e2e

folder is inside of the app folder.

Create a Library

Libraries are ideal places to house things like UI components or data access services for use in multiple applications.

We can add new libs to an Nx Workspace by using the AngularCLI

generate

command, just like adding a new app. Nx has a schematic named

lib

that can be used to add a new Angular module lib to our workspace:

ng generate lib shared-components

We’ll get several prompts at the command line regarding tooling, testing, setup, and routing. Since we’re not actually going to be using this library, the answers to these questions are irrelevant -- go ahead and just accept all of the defaults. However, it’s good to know how easily customizable libs are from the command line, from routing and lazy loading to tooling and setup.

Running this command will create a

libs/shared-components

with its own

src

folder and config files.

We can easily add components to this library by passing a

project

option to the CLI. Let's take advantage of the

shortcut for

generate

and the

shortcut

component

and run the following command:

ng g c pet-list --export=true --project=shared-components

Since this is a shared library, I’ve added

export=true

to export the component from the

NgModule

Now that we know the basics of Nx, let’s explore one of its lesser known but incredibly powerful features: the ability to create custom workspace schematics.

Creating a Custom Auth Schematic

You’re actually already familiar with schematics — they’re what the Angular CLI uses to create new components, services, and more when you run the

ng generate

command. You can also write your own schematics from scratch, whether or not you’re using Nx. The beauty of Nx, though, is that it does all the hard work of wiring up your custom schematics so that it’s easy to run them in your workspace.

Custom schematics are frequently used for two broad purposes:

To enforce styles or standards at your organization.
To generate custom code specific to your organization.

“Custom @angular CLI schematics are used to enforce styles or standards and to generate custom code.”
Tweet This

We’re going to focus on the former in this tutorial because generating custom code with the schematics API requires some knowledge of the TypeScript abstract syntax tree and is a little out of our scope in this tutorial.

Some examples of good ideas for custom schematics that enforce styles or standards are:

Enforcing directory structure or application architecture.
Enforcing patterns for data access like NgRx.

Since authentication is a subject dear to our hearts here at Auth0, let’s create a schematic for developers to use when adding an authentication module to their applications. We’d like it to do four things:

Adhere to a naming convention of prefixing "auth-" to the files.
Create an authentication module and import it into the project’s
```
AppModule
```
.
Create an empty service that will hold our authentication code.
Create an empty
```
CanActivate
```
guard that will hold an authentication route guard.

We can accomplish all of this in a single schematic that will accept the name of the module and the project we’re adding it to as arguments. This will let our developers working on the pet adoption system quickly add the correct scaffolding to any application they’re building on the project.

Let’s get started!

Generate the Custom Schematic

The first step to creating a custom schematic is to use Nx to generate the initial code. We can do this by running this command:

ng g workspace-schematic auth-module

(Notice that I've used the

shortcut for

generate

again.)

The

workspace-schematic

schematic (I know, it’s so meta) creates the

auth-module

folder inside of

tools/schematics

. This new folder contains two files:

schema.json

and

index.ts

Update the Schema

Schema.json

contains metadata for our custom schematic like the options used with it. If we open it, we’ll see this default code:

// tools/schematics/auth-module/schema.json
{
  "$schema": "http://json-schema.org/schema",
  "id": "auth-module",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Library name",
      "$default": {
        "$source": "argv",
        "index": 0
      }
    }
  },
  "required": ["name"]
}

By default, we’re able to pass a

name

property, which is a

string

, to our schematic. The

$default

parameter tells us that it will assume that the first argument given to this command is the value for the

name

property. Feel free to change the description of the

name

property to something more specific, like, "Auth module name."

Let’s also add another property to this file to specify the project to which we’ll add our new authentication module. Underneath the name property, add the following:

// tools/schematics/auth-module/schema.json
// ...above code remains the same
// add under the name property:
"project": {
  "type": "string",
  "description": "Project to add the auth module to"
}
// ...below code remains the same

Let’s make it required, too, by adding it to the

required

array. The finished file will look like this:

// tools/schematics/auth-module/schema.json
{
  "$schema": "http://json-schema.org/schema",
  "id": "auth-module",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Auth module name",
      "$default": {
        "$source": "argv",
        "index": 0
      }
    },
    "project": {
      "type": "string",
      "description": "Project to add the auth module to"
    }
  },
  "required": ["name", "project"]
}

We could add any other options with their types here if we needed them. If you look at

schema.json

for the official component schematic, for example, you’ll see familiar

boolean

options like

spec

and

inlineTemplate

Write the Custom Schematic

We’re now ready to write the custom schematic implementation. This lives in the generated

index.ts

file. Let’s open it up and begin to create our

auth-module

schematic. We’ll see the following code generated by Nx:

// tools/schematics/auth-module/index.ts
import { chain, externalSchematic, Rule } from '@angular-devkit/schematics';

export default function(schema: any): Rule {
  return chain([
    externalSchematic('@nrwl/schematics', 'lib', {
      name: schema.name
    })
  ]);
}

Let’s break down what’s happening here so that we can build off of it.

First, we’re importing the

chain

and

externalSchematic

functions, as well as the

Rule

type, from

@angular-devkit/schematics

. We then use all of those imports in the exported function. What are these things, though?

We often say that schematics are like blueprints when you’re building a house. In that analogy, a

Rule

is a page or section of a blueprint. Rules are the individual pieces of the schematic that tell the CLI how to modify the file system, represented as a

Tree

in schematics. Trees allow us to mutate the file system with file creations, updates, and deletions. Generally, anything we can do with the file system we can do with the tree. Unlike the file system, though, trees use a transactional structure. No changes are made to the actual file system until the entire schematic runs. If part of the schematic fails, any changes to the file system are rolled back.

Rules, then, are functions that take in the current tree and return either a modified tree or another rule. This means that rules are also composable. We can combine rules using the

chain

function like we’re doing in this example. There are other operators, too, like

branchAndMerge

and

mergeWith

. You’ll see these functions throughout the official CLI schematics code.

We can also use the

externalSchematic

function here to refer to an outside schematic and compose its rules onto our custom schematic. In the boilerplate generated by Nx, we start with a rule that simply runs the

lib

schematic built into Nx, which is in the

@nrwl/schematics

collection.

The heart of the schematic is the exported function:

// tools/schematics/auth-module/index.ts
export default function(schema: any): Rule {
  return chain([
    externalSchematic('@nrwl/schematics', 'lib', {
      name: schema.name
    })
  ]);
}

This function takes in a

schema

and returns a

Rule

. The

schema

should match the structure in

schema.json

. At the core, all schematics are just functions that return rules that modify the file system. You’ll often see many rules defined in a schematic, as well as helper functions, but in the end, only one function gets exported. This function will have any necessary rules chained, branched, or merged together.

The simplest possible custom schematic is one that takes advantage of chaining together existing rules. This is particularly useful at large organizations to enforce best practices and architecture patterns. For example, you may want to ensure that everyone on the team always generates components with inline styles and with an accompanying model as a TypeScript interface. You could easily chain together the

component

schematic with the

interface

schematic to make this easy for everyone in the organization to do.

We’re going to follow a similar pattern here. We want to make sure that everyone who adds authentication to a project always adds a separate module, a service, and a

CanActivate

guard. We’ll use our new tools—the

chain

and

externalSchematic

functions—to do this.

Let’s first replace Nx

lib

with a call to the

module

schematic, keeping it inside of the array being passed into the

chain

function:

// tools/schematics/auth-module/index.ts
// ...above code remains the same
// replace nx lib with this:
externalSchematic('@schematics/angular', 'module', {
  project: schema.project,
  name: schema.name,
  routing: true,
  module: 'app.module.ts'
})

Notice that we’re first passing in the collection (

@schematics/angular

), followed by the schematic name (

module

), followed by an options object. The options object contains values for any options for the external schematic. We’re passing in the project, name, and root module name of

app.module.ts

. We’re also setting the

routing

flag to

true

to add routing to the authentication module. This makes it easy for someone to add routes to the authentication module, such as a

callback

route or routes for logging in and out.

For the calls to the

service

and

guard

schematics, we’ll need to import

path

at the top of our file:

// tools/schematics/auth-module/index.ts
// ...previous imports
import * as path from 'path';

This will let us specify file paths regardless of whether the user is using a Windows or Linux-based operating system. Add the following to the array after the

module

schematic (don’t forget a comma!):

// tools/schematics/auth-module/index.ts
// ...above code remains the same
externalSchematic('@schematics/angular', 'service', {
  project: schema.project,
  name: schema.name,
  path: path.join(
    'apps',
    schema.project,
    'src',
    'app',
    schema.name,
    'services'
    )
})
// ...end of the array and chain function

When we run this schematic, it will generate our service inside of

apps/{project}/src/app/{schema}/services

. You could easily change this to a different structure if you’d like. Do you notice how easy these schematics make standardizing and enforcing code organization?

Our last call is to the

guard

schematic and it’s almost identical. Add this after the

service

schematic (and, again, don’t forget the comma!):

// tools/schematics/auth-module/index.ts
// ...above code remains the same
externalSchematic('@schematics/angular', 'guard', {
  project: schema.project,
  name: schema.name,
  path: path.join(
    'apps',
    schema.project,
    'src',
    'app',
    schema.name,
    'services'
    )
})
// ...end of the array and chain function

This will generate a guard in the same place as the authentication service.

Our schematic is nearly finished now. It will create a module, service, and guard with the name we give it and for the project we specify. Let’s add one final touch: let’s throw an error if the user doesn’t prefix their new authentication module with

auth-

To do this, we can add the following

if

statement inside of our function on line 5, just before we return our chain of rules:

// tools/schematics/auth-module/index.ts
// ...above code remains the same
// add above the returned chain function:
if (!schema.name.startsWith('auth-')) {
  throw new Error(`Auth modules must be prefixed with 'auth-'`);
}
// ...below code remains the same

We’ll now see an error if we don’t adhere to the naming guidelines. Neat!

The finished code for our custom schematic looks like this:

import { chain, externalSchematic, Rule } from '@angular-devkit/schematics';
import * as path from 'path';

export default function(schema: any): Rule {
  if (!schema.name.startsWith('auth-')) {
    throw new Error(`Auth modules must be prefixed with 'auth-'`);
  }

  return chain([
    externalSchematic('@schematics/angular', 'module', {
      project: schema.project,
      name: schema.name,
      routing: true,
      module: 'app.module.ts'
    }),
    externalSchematic('@schematics/angular', 'service', {
      project: schema.project,
      name: schema.name,
      path: path.join(
        'apps',
        schema.project,
        'src',
        'app',
        schema.name,
        'services'
      )
    }),
    externalSchematic('@schematics/angular', 'guard', {
      project: schema.project,
      name: schema.name,
      path: path.join(
        'apps',
        schema.project,
        'src',
        'app',
        schema.name,
        'services'
      )
    })
  ]);
}

Remember that we’re only generating the scaffolding of our authentication setup with this schematic. To learn how to properly implement authentication in your service and guard, check out our Angular authentication tutorial. We’ve also got an NgRx authentication tutorial for you if you’re taking advantage of NgRx in your project. To use either of these tutorials to set up Auth0 in your application, first sign up for a free Auth0 account here.

Run the Custom Schematic

Now that we’ve got the schematic written, let’s test it out. Nx already did the work of wiring it up to be used in our workspace, so we don’t need to worry about that. To run our new

auth-module

schematic, run the following command:

npm run workspace-schematic -- auth-module auth-adoption --project=adoption-ui

This command runs the

workspace-schematic

script that’s part of Nx. We use the

--

operator to pass options into that script like the names of the module and project. (If you’re using Yarn, you can ditch the

--

operator and run

yarn workspace-schematic auth-module

with the rest of the options.)

Once the schematic runs, we’ll see the resulting files inside of the

src

folder of the

adoption-ui

application. Our

auth-adoption

module and its routing module will be there, as well as the

services

folder containing the

auth-adoption

service and route guard.

Don’t forget to also test out our naming requirement. Try to run the command again but without the

auth-

prefix. You should see

Auth modules must be prefixed with 'auth-'

as an error in your console. You’ll also see an error if you fail to specify the project name.

All of the finished code can be found in this repository.

Conclusion

Our custom authentication schematic accomplishes a lot with under 50 lines of code:

It automatically scaffolds an authentication module, service, and route guard.
It enforces both an architecture standard and a naming standard.
It can easily be reused by developers for future products.

Since writing custom schematics for the first time can be a bit of a challenge, it helps to have Nx do a lot of the heavy lifting. That’s really what Nx does best: automating and simplifying Angular development at scale.

To learn more about custom schematics, check out the introduction on the Angular blog, this great tutorial on Generating Custom Code by Manfred Steyer, and this presentation on custom schematics by Brian Love. And, of course, the best place to see examples of custom schematics is the source code for the Angular schematics.

We’ve really only scratched the surface of what Nx can do. To learn more about Nx, including features like the visual dependency graph, dependency constraints, and the ability to run only affected tests, check out the official Nx documentation, the nx-examples repo, and this free video course on Nx by Justin Schwartzenberger.

Special thanks to Jason Jean from Nrwl for doing some pair programming with me to answer my questions about Nx and custom schematics. Thanks, Jason!

About the author

Sam Julien

Director of Developer Relations

I'm Director of Developer Relations and a Google Developer Expert for Angular and Web Technologies. I believe anyone who wants to learn to code should be able to learn code and I love teaching. When I'm not coding or writing, you'll find me outside hiking or camping in the beautiful Pacific Northwest.View profile

Create Your First Custom Angular CLI Schematic with Nx