Create Your First Angular Schematics

I experienced a lot of pain points when I first started using Angular; I needed to open up so many files just to create a simple Hello World app. Luckily, Angular CLI took away a lot of my initial troubles. 

Angular CLI is a command-line tool that creates a simple Angular project. Angular CLI asks you questions about your app and, based on your answers, it determines the routing and the stylesheet format. How does Angular CLI do this? It uses Schematics. 

Now, what is a Schematic? It’s an API that manages files and adds new dependencies in Angular projects, which can also work in non-Angular projects.

If you’d rather watch a video, I created a screencast of this tutorial.

To see Schematics in action, install Angular CLI:

npm install -g @angular/cli@7.3.0

Then create a new Angular project:

$ ng new my-cool-app
? Would you like to add Angular routing? Yes
? Which stylesheet format would you like to use? (Use arrow keys)
❯ CSS
  Sass   [ http://sass-lang.com   ]
  Less   [ http://lesscss.org     ]
  Stylus [ http://stylus-lang.com ]

That’s it! A Schematic can prompt you with questions, make changes based on your responses, and look good while doing it!

Use Schematics to add Authentication to Your Angular App

Want to see something even cooler? You can add Okta support to an Angular CLI-generated app with the following command:

ng add @oktadev/schematics

This will prompt you for an OIDC issuer and client ID. To get those values, create an Okta Developer account.

Once you’ve verified your email, log in to your account, and navigate to Applications > Add Application, select Single-Page App, and click Next. Give your app a name you’ll remember, change the port from   8080 to 4200 in the base and redirect URIs, and click Done. Your settings should look similar to the screenshot below.

Copy the Client ID from this screen and save it in a temporary file. Click on Dashboard, and you’ll find an Org URL in the top right corner. Copy this value into the file as well. If you haven’t run the   ng add @oktadev/schematics command. For the issuer URL, use your Org URL + /oauth2/default. You can see a screenshot of my values and the process below.

Now you can run your app with ng serve, navigate to http://localhost:4200, and you’ll see a login button at the bottom. Click on it to authenticate with Okta. When you’re redirected back to your app, it’ll be replaced with logout button.

How sweet is that?! Without this schematic, you have to perform the following steps (from Build a Basic CRUD App with Angular 7.0 and Spring Boot 2.1):

1. Run npm install @okta/okta-angular
2. Update app.module.ts to add config and initialize
3. Add callback route to app-routing.module.ts
4. Add and configure an HttpInterceptor to add an Authorization header
5. Add login and logout buttons
6. Add authenticated logic to app.component.ts
7. Generate HomeComponent and configure with authentication

Instead of having to do these seven steps, our Schematics does it all for you in less than 30 seconds!

Now that you’ve seen the power of Schematics, let’s dive in and learn how to create one.

Angular CLI, Angular Schematics, and Angular DevKit

The Angular CLI can be used to create, manage, build, and test your Angular projects. It’s built on DevKit, which resides in the same monorepo on GitHub. DevKit was built to provide libraries that can be used to manage, develop, deploy, and analyze your code. DevKit has a schematics-cli command line tool that you can use to create your own Schematics.

Create Your First Schematic

To create a Schematics project, first install the Schematics CLI:

npm i -g @angular-devkit/schematics-cli@0.13.1

Then run schematics to create a new blank project:

schematics blank --name=my-component

This will create a number of files for you.

CREATE /my-component/README.md (639 bytes)
CREATE /my-component/package.json (539 bytes)
CREATE /my-component/tsconfig.json (656 bytes)
CREATE /my-component/.gitignore (191 bytes)
CREATE /my-component/.npmignore (64 bytes)
CREATE /my-component/src/collection.json (231 bytes)
CREATE /my-component/src/my-component/index.ts (318 bytes)
CREATE /my-component/src/my-component/index_spec.ts (474 bytes)

There’s a package.json that handles your project’s dependencies. There’s also a src/collection.json that defines the metadata for your project. If you look at collection.json, you’ll see the following:

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "my-component": {
      "description": "A blank schematic.",
      "factory": "./my-component/index#myComponent"
    }
  }
}

You can see that the my-component schematic points to a factory function in my-component/index.ts. Crack that open and you’ll see the following:

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';

export function myComponent(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    return tree;
  };
}

There’s also a test in my-component/index_spec.ts.

import { Tree } from '@angular-devkit/schematics';
import { SchematicTestRunner } from '@angular-devkit/schematics/testing';
import * as path from 'path';

const collectionPath = path.join(__dirname, '../collection.json');

describe('my-component', () => {
  it('works', () => {
    const runner = new SchematicTestRunner('schematics', collectionPath);
    const tree = runner.runSchematic('my-component', {}, Tree.empty());

    expect(tree.files).toEqual([]);
  });
});

One cool thing about Schematics is they don’t perform any direct actions on your filesystem. Instead, you specify what you’d like to do to a Tree. The Tree is a data structure with a set of files that already exist and a staging area (of files that will contain new/updated code). You can see in the code above that nothing is really happening, the test even proves the tree is empty!

Add a Hello World Example

Let’s do something slightly more interesting than making sure it runs and create a hello.ts file. Modify my-component/index.ts to have a tree.create() command.

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';

export function myComponent(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    tree.create('hello.ts', 'console.log("Hello, World")');
    return tree;
  };
}

Then update my-component/index_spec.ts to expect this file.

describe('my-component', () => {
  it('works', () => {
    const runner = new SchematicTestRunner('schematics', collectionPath);
    const tree = runner.runSchematic('my-component', {}, Tree.empty());

    expect(tree.files).toEqual(['/hello.ts']);
  });
});

Run npm test, and everything should pass. Want to prove it works? Run the following command from the my-componentdirectory.

schematics .:my-component

This looks like it creates a file, but it does not. This is because schematics runs in debug mode by default. You can bypass this by adding --dry-run=false to the command.

Run schematics .:my-component --dry-run=false, and hello.ts will be created on your hard drive. If you try running the command again, it’ll fail because the file already exists.

schematics .:my-component --dry-run=false
An error occured:
Error: Path "/hello.ts" already exist.

When using Schematics, it’s unlikely you’re going to want to create files and their contents manually. More than likely, you’ll want to copy templates, manipulate their contents, and put them in the project you’re modifying. Luckily, there’s an API for that.

Copy and Manipulate Templates

Create a src/my-component/files/src/app directory to hold your templates.

mkdir -p src/my-component/files/src/app

Create an app.component.ts file in src/my-component/files/src/app and put the following code in it:

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  name = '<%= name %>';
}

The <%= name %> variable is an option you’ll pass in when running this Schematic. Create an app.component.html file with some HTML that reads the name variable.

<div style="text-align:center">
  <h1>
   Hello, {{ name }}
  </h1>
</div>

<router-outlet></router-outlet>

After creating these files, your src/my-component directory should look as follows.

src/my-component/
├── files
│   └── src
│       └── app
│           ├── app.component.html
│           └── app.component.ts
├── index.ts
└── index_spec.ts

In order to define the name prompt, create a schema.json file in the src/my-component directory.

{
  "$schema": "http://json-schema.org/schema",
  "id": "SchematicsMyComponent",
  "title": "My Component Schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Your Name",
      "x-prompt": "What is your name?"
    }
  },
  "required": ["name"]
}

Then, update src/collection.json to reference this file in a schema property.

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "my-component": {
      "description": "A blank schematic.",
      "factory": "./my-component/index#myComponent",
      "schema": "./my-component/schema.json"
    }
  }
}

Modify src/my-component/index.ts so you can get your generated project’s path and copy templates.

import {
  apply,
  MergeStrategy,
  mergeWith,
  move,
  Rule,
  SchematicContext,
  template,
  Tree,
  url
} from '@angular-devkit/schematics';
import { join, normalize } from 'path';
import { getWorkspace } from '@schematics/angular/utility/config';

export function setupOptions(host: Tree, options: any): Tree {
  const workspace = getWorkspace(host);
  if (!options.project) {
    options.project = Object.keys(workspace.projects)[0];
  }
  const project = workspace.projects[options.project];

  options.path = join(normalize(project.root), 'src');
  return host;
}

export function myComponent(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    setupOptions(tree, _options);

    const movePath = normalize(_options.path + '/');
    const templateSource = apply(url('./files/src'), [
      template({..._options}),
      move(movePath)
    ]);
    const rule = mergeWith(templateSource, MergeStrategy.Overwrite);
    return rule(tree, _context);
  };
}

Want to prove it all works? Write a test for it.

Test Your Schematics

To write a test that reads from a workspace and gets the project information, you’ll need to run a couple of external schematics in your test: one to create a workspace and one to create a project. You’ll need to install @schematics/angular to make this possible.

npm i -D @schematics/angular@7.3.0

Then, modify src/index_spec.ts to have workspace options, app-generation options, and schema options.

import { SchematicTestRunner, UnitTestTree } from '@angular-devkit/schematics/testing';
import * as path from 'path';

describe('my-component', () => {

  const collectionPath = path.join(__dirname, '../collection.json');
  const schematicRunner = new SchematicTestRunner(
    'schematics',
    path.join(__dirname, './../collection.json'),
  );

  const workspaceOptions: any = { 
    name: 'workspace',
    newProjectRoot: 'projects',
    version: '0.5.0',
  };

  const appOptions: any = { 
    name: 'schematest'
  };

  const schemaOptions: any = { 
    name: 'foo'
  };

  let appTree: UnitTestTree;

  beforeEach(() => { 
    appTree = schematicRunner.runExternalSchematic('@schematics/angular', 'workspace', workspaceOptions);
    appTree = schematicRunner.runExternalSchematic('@schematics/angular', 'application', appOptions, appTree);
  });

  it('works', () => {
    const runner = new SchematicTestRunner('schematics', collectionPath);
    runner.runSchematicAsync('my-component', schemaOptions, appTree).toPromise().then(tree => {
      const appComponent = tree.readContent('/projects/schematest/src/app/app.component.ts'); 
      expect(appComponent).toContain(`name = '${schemaOptions.name}'`); 
    });
  });
});

Run npm test and rejoice in your victory!

Run Your Schematics with Angular CLI

Before publishing your Schematics to npm, it’s a good idea to do some basic manual testing with Angular CLI. Create a new project:

ng new my-test-app --routing --style css

Then run npm link /path/to/schematics. I created mine in the same directory as my Schematics project, so the command I ran was:

cd my-test-app
npm link ../my-component

Run your schematic with the ng g command.

ng g my-component:my-component

When I tried this, it prompted me for my name, but then failed to overwrite the templates.

? What is your name? Matt
ERROR! src/app/app.component.html already exists.
ERROR! src/app/app.component.ts already exists.
The Schematic workflow failed. See above.

As you can see, my test passes, but it doesn’t work in the real world. To fix this, open my-component/src/index.ts and add a forEach() after move(movePath).

import { FileEntry, forEach } from '@angular-devkit/schematics';

...

export function myComponent(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    setupOptions(tree, _options);

    const movePath = normalize(_options.path + '/');
    const templateSource = apply(url('./files/src'), [
      template({..._options}),
      move(movePath),
      // fix for https://github.com/angular/angular-cli/issues/11337
      forEach((fileEntry: FileEntry) => {
        if (tree.exists(fileEntry.path)) {
          tree.overwrite(fileEntry.path, fileEntry.content);
        }
        return fileEntry;
      }),
    ]);
    const rule = mergeWith(templateSource, MergeStrategy.Overwrite);
    return rule(tree, _context);
  };
}

Run npm run build in your my-component directory to rebuild your Schematics. Then run the ng g command again. Everything should work this time.

$ ng g my-component:my-component
? What is your name? Matt
UPDATE src/app/app.component.html (109 bytes)
UPDATE src/app/app.component.ts (207 bytes)

Publish Your Schematics to npm

The most important thing to know when publishing your Schematics to npm is that the default .npmignore ignores all TypeScript files. That means if you run npm publish, your compiled Schematic will be and your HTML template, will be published, but your TypeScript template will not be.

Modify .npmignore, so it doesn’t exclude your template files.

It took me several hours to figure this out. So simple, yet so subtle.

When you’re ready to publish your Schematics to npm, run npm publish. If you want to remove a published package, you can do it within the first 72 hours:

• Run npm unpublish <package_name> -f to remove the entire package thanks to the -f or force flag
• Use npm unpublish <package_name>@<version> to remove a specific version

You can learn more about the unpublish command and the Unpublish Policy in npm’s documentation.

Add Support for ng add with Angular CLI

A slick feature of Angular CLI is its ng add command. You can use it to invoke schematics and add features like PWA support and Angular Material to your projects. For example:

ng add @angular/pwa
ng add @angular/material

You can support for ng add $your-schematic too! Open my-component/src/collection.json and add a new ng-add schematic.

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "my-component": {
      "description": "A blank schematic.",
      "factory": "./my-component/index#myComponent",
      "schema": "./my-component/schema.json"
    },
    "ng-add": {
      "factory": "./ng-add/index",
      "description": "Add schematic",
      "schema": "./my-component/schema.json"
    }
  }
}

Create src/ng-add/index.ts and add the code necessary for it to invoke the my-component schematic.

import { chain, Rule, schematic, SchematicContext, Tree, } from '@angular-devkit/schematics';

export default function (options: any): Rule {
  return (host: Tree, context: SchematicContext) => {
    return chain([
      schematic('my-component', options)
    ])(host, context);
  };
}

Run npm run build in your my-component project. Now you should be able to run ng add my-component in your my-test-app project. Pretty slick, eh?

Learn More about Angular and Schematics

I hope you’ve enjoyed this quick tutorial about Schematics. I learned a lot about them when developing OktaDev Schematics. I encourage you to check out its source code as well as Angular CLI’s Schematics. In particular, I learned a lot from the PWA Schematic.

Have you read this far? Thanks! In case you missed it, you can create a secure Angular app in minutes! 

ng new my-secure-app --routing
cd my-secure-app
// create a SPA app on Okta, copy settings
ng add @oktadev/schematics

After you run these commands, you’ll have the Okta Angular SDK installed and configured in your project. You can learn all about its features in our Angular + Okta documentation.

You can find the source code for the example schematic in this post on GitHub at oktadeveloper/okta-angular-schematics-example.

OktaDev Schematics now has support for React, Vue, and Ionic! See the following blog posts for more information.

• Use Schematics with Vue and Add Authentication in 5 Minutes
• Use Schematics with React and Add OpenID Connect Authentication in 5 Minutes
• Build an Ionic 4 App with User Login and Registration

We like to write about Angular on this blog. Here are some of our recent Angular posts:

• Build Your First PWA with Angular
• Build a Basic Website with ASP.NET MVC and Angular
• Angular 7: What’s New and Noteworthy + OIDC Goodness
• [Video] Build a Basic CRUD App with Angular 7.0 and Spring Boot 2.1
• Build a Simple Web App with Express, Angular, and GraphQL

And here’s a bunch of articles I used to learn about Schematics:

• Schematics — An Introduction
• How To Create Your First Custom Angular Schematics With Ease
• Making an Addable Angular Package Using Schematics
• Angular Schematics: Simple Schematic

If you liked this post, you’ll probably like future posts! Follow us @oktadev on Twitter to find out when we publish them. We also publish screencasts on our YouTube Channel.

Use Angular Schematics to Simplify Your Life was originally published on the Okra Developer Blog on February 13, 2019.