Angular Schematics

ANGULARANGULAR
SCHEMATICSSCHEMATICS
THE UNKNOWN HEROTHE UNKNOWN HERO

CHRIS NORINGCHRIS NORING
CLOUD DEVELOPER EXPERT AT MICROSOFTCLOUD DEVELOPER EXPERT AT MICROSOFT
Google Developer Expert in Angular and Web Techs
@chris_noring
https://so chris.github.io
Published author
Public Speaker
So ware Engineer

WORKFLOW TOOLWORKFLOW TOOL
CAN APPLY TRANSFORMS TO YOUR PROJECTCAN APPLY TRANSFORMS TO YOUR PROJECT
example of usage:
scaﬀold: new components, services,
update your code to fix breaking changes in
dependencies.
or add a new configuration option or framework to
an existing project

ANGULAR CLI - SECRET SAUCEANGULAR CLI - SECRET SAUCE
GENERIC FACILITY TO SUPPORT THE CLIGENERIC FACILITY TO SUPPORT THE CLI
SCAFFOLDINGSCAFFOLDING
improve your development productivity
Ease uf use and development
Extensibility and reuseability
Atomicity
Asynchronicity

TREETREE
OVER FILE SYSTEMOVER FILE SYSTEM
not aﬀecting the file system directly,
you describe what transformations you
want done on a Tree

INSTALLATIONINSTALLATION
npm install -g @angular-devkit/schematics-cli
This will install a schematics
executable, which you can use to
create a blank Schematics project

EXAMPLEEXAMPLE
YOUR FIRST SCHEMATICYOUR FIRST SCHEMATIC

schematics blank --name=my-component

index.ts, where our rules live
collection.json, a description of our project

INDEX.TSINDEX.TS
return a function of type Rule
options input, is an object representing command
line args
inner function takes Tree and SchematicContext,
tree is file tree

COLLECTION.JSONCOLLECTION.JSON
description, description of project
factory, points to the directory/starter module

BUILD AND RUNBUILD AND RUN
--name=test, command line arg
npm run build
schematics .:my-component --name=test

not surprised, cause our Rule factory function does
nothing

EXAMPLEEXAMPLE
SCAFFOLD SOME FILES, WITH CONTENTSCAFFOLD SOME FILES, WITH CONTENT

create files, with content
tree.create(filename, file-content)

let's create a build and run script

we didn't actual create any files, we are in dry-run
mode
It shows what would happen if applied
to a file system

oh, so they were created in the in the project

Just add the follwing to your schematics executable
--dry-run=false

There are four methods that directly create a change in
a Tree
create
delete
rename
overwrite

TIPS AND TRICKSTIPS AND TRICKS

watch mode, rebuild your project on changes
npm run build -w

Debugging
node --inspect-brk <path_to_schematics>/schematics
.:myComponent --name=test

TESTING OUT YOUR SCHEMATICSTESTING OUT YOUR SCHEMATICS

scaﬀold an Angular project
npm link to the schematics
ng generate

npm link <path to schematics>
// tip: run pwd and copy result

ng generate my-service:my-service someName

EXAMPLEEXAMPLE
USING AN EXISTING SCHEMATICUSING AN EXISTING SCHEMATIC

WHAT IS A COLLECTION?WHAT IS A COLLECTION?
Schematics Collections are sets of named
schematics, that are published and installed by
users.
Angular team publishes and maintains the oﬀicial
@schematics/angular collection e.g component,
module, application

Scenario: add some disclaimer text on top of
component

We start by scaﬀolding a project
schematics blank --name=my-external

We need to add two new helper functions:
chain, is a RuleFactory provided by Schematics
library, chains multiple rules together
externalSchematic, also a rule factory

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

install @schematics/angular
imports and runs the schematic
externalSchematic('@schematics/angular', 'component', options)

Next part is our schematic that needs to
go through all files
for each file list it's content and add header text

const headerText = `
@copyright ngVikings, by the community, for the community
`

(tree: Tree, _context: SchematicContext) => {
tree.getDir(options.sourceDir)
.visit(filePath => {
if (!filePath.endsWith('.ts')) {
return;
}
const content = tree.read(filePath);
if (!content) {
return;
}
// Prevent from writing license to files that already ha
if (content.indexOf(licenseText) == -1) {
tree.overwrite(filePath, headerText + content);
}

Building and running the above

EXAMPLEEXAMPLE
SCAFFOLD BASED ON TEMPLATESSCAFFOLD BASED ON TEMPLATES

We want to:
define scaﬀold files
define templates
replace template content with commandline args

schematics blank --name=my-template

define template file
you can place them where you want but your
tsconfig.json is set to ignore /files

let's create some template files

we are looking to replace name
<%= name %>

export function myTemplate(_options: any): Rule {
_options.path = _options.path ? normalize(_options.path) : _
const templateSource = apply(url("./files"), [
filterTemplates(_options),
template({
...stringUtils,
..._options
}),
move("/src/app/my-template")
// what to do with the files in here
]);
return chain([branchAndMerge(chain([mergeWith(templateSource
}

let's break it down
filterTemplates, function that ensures we get the
template files we want
template, function that takes a template and
content and merge them
move, where we place the end result

if service is NOT specified as command line arg, then
we don't include it else just filter out .bak files
function filterTemplates(options: any): Rule {
if (!options.service) {
return filter(
path =>
!path.match(/.service.ts$/) &&
!path.match(/-item.ts/) &&
!path.match(/.bak$/)
);
}
return filter(path => !path.match(/.bak$/));
}

stringUtils obj containing helper functions for our
template, e.g classify _options obj containing
data that we want to pass to our template, e.g name
template({
...stringUtils,
..._options
})

classify comes from stringUtils, ensures we
get capital letter name name from _options
export class <%= classify(name) %> {
getData() {
// fetch data here
}
}

THE ANATOMY OF A TREETHE ANATOMY OF A TREE

is a list of type Action
let's look at what an Action is
tree.actions // Action[]

diﬀerent type of actions,
path looks interesting
kind is a property that says what type of CRUD
export declare type Action =
CreateFileAction |
OverwriteFileAction |
RenameFileAction |
DeleteFileAction;
export interface ActionBase {
readonly id: number;
readonly parent: number;
readonly path: Path;
}

ok, an Action seems to represent our intent, how do
we read from it?

tree.actions.forEach(action => {
console.log("action kind", action.kind);
console.log("action path", action.path);
let fe = tree.get(action.path);
if (fe) {
console.log("action content", fe.content.toString("utf8"))
}
});

ok so we can list all the things the tree is about to do,
with its content

This is internals, it might change in the near future, still
interesting though

UNDERSTANDING YOUR CODEUNDERSTANDING YOUR CODE
USING THE TYPESCRIPT COMPILERUSING THE TYPESCRIPT COMPILER

We can send in our code into the Typescript compiler
and it will give us a tree representation back

read file
convert file content into a SourceFile
investigate your tree

very simple file
class DemoClass {
constructor(otherDemo: DemoClass, param: string) {}
}

read, create source file
let node = ts.createSourceFile(
'demo.ts',
content,
ts.ScriptTarget.Latest,
true
);

let's try to print our nodes in a nice way

thank you Manfred Steyer for this function
function showTree(node: ts.Node, indent: string = ' '): voi
console.log(indent + ts.SyntaxKind[node.kind]);
if (node.getChildCount() === 0) {
console.log(indent + ' Text: ' + node.getText());
}
for(let child of node.getChildren()) {
showTree(child, indent + ' ');
}
}
showTree(node);

we need to flatten the tree into a list of nodes, for
convenience
we need to find the correct position to do our
change
we need to create a Change object that says path,
position of change and with what
content
lastly we need to call the following on the tree
beginUpdate, to get a recorder commitUpdate
to make the changes stick
admire our work

gives us a flattened list of Nodes
const nodes = getSourceNodes(componentSource);

you can query nodes by type, find the type you need
according to our AST tree
function getNodeByType(nodes: ts.Node[], type: ts.SyntaxKind)
return nodes.find(n => n.kind === type)[0];
}
// e.g
const node = getNodeByType(
nodes,
ts.SyntaxKind.ConstructorKeyword
)

once you have the correct node, simply insert
before/a er your node
function createChange(path: any, what: string, pos: number) {
return new InsertChange(path, pos, what);
}
createChange('path-to-file', 'insert this', node.pos+1)

interate our list of changes and commit/ save
function applyChanges(path: string, content: string, changes:
tree.create(path, content);
const exportRecorder = tree.beginUpdate(path);
for (const change of changes) {
if (change instanceof InsertChange) {
exportRecorder.insertLeft(change.pos, change.toAdd);
}
}
tree.commitUpdate(exportRecorder);
}

all together now :)
function myRule(options): Rule {
return (tree: Tree, _context: SchematicContext) => {
const componentSource = getTsSource( componentPath,
componentContent
);
const nodes = getSourceNodes(componentSource);
const node = getNodeByType( nodes,
ts.SyntaxKind.ConstructorKeyword
);
const change = createChange( componentPath,
'insert this',
node.pos+1
);
applyChanges( componentPath,
componentContent, [ change ], tree);

FURTHER READINGFURTHER READING
Intro article to Schematics article by Hans from Angula
https://blog.angular.io/schematics-an-introduction-
dc1dfbc2a2b2
Manfred Steyer, 5 blog post series,
https://www.so warearchitekt.at/post/2017/10/29/ge
custom-code-with-the-angular-cli-and-schematics.asp
Manfred Steyer, free book on Schematics,
https://leanpub.com/angular-schematics
Jorge Cano, article, https://medium.com/@jorgeucan
fist-angular-schematics-f711d70cb37c

SUMMARYSUMMARY
Workflow tool
Performs changes on a Tree
Consist of Rules you apply on a Tree
Can be used for scaﬀolding but also update code
is the secret sauce behind Angular-CLI

Angular Schematics

More Related Content

What's hot (20)

Similar to Angular Schematics (20)

More from Christoffer Noring (20)

Recently uploaded (20)

Angular Schematics