Morioh
Login
Libetia A

Libetia A

4 years ago

How to Create Angular Schematics for Developers

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.

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 ]

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
Make sure you are in an Angular project directory before you run this command. Also, make sure your project is checked into source control before you run it.

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.

Without this schematic, you have to perform the following steps

  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
If you’re on Windows, mkdir -p will only work if you’re using Bash on Windows. If you’re not using Bash, you’ll need to md each directory.

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 %>’;

}
You can ignore any compilation errors you get in this file. It’s just a template and should compile in your target project.

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
You can also use npm pack in your schematics project, then npm install /path/to/artifact.tar.gz in your Angular project. This mimics npm install more than npm link.

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) =&gt; {
    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.

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

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?

Conclusion

I hope you’ve enjoyed this quick tutorial about Schematics. Thanks for reading. Keep Visiting.

Originally published on dzone.com

#angular #angular-js #devops #web-development

How to Create Angular Schematics for Developers
7 Likes48.75 GEEK