schematics-wdc-19

Slides of the Dev-session about Angular shematics: https://www.web-developer-conference.de/programm/#/talk/schematics-codegenerierung-nach-mas

Transcript

1. Angular Schematics
2. Gregor Doroschenko Gregor Woiwode
3. Gregor Doroschenko
4. Gregor Woiwode
5. Agenda ▪ What is a schematic? ▪ Dive into schematic projects ▪ Rules ▪ Templates ▪ ng-add ▪ ng-update
6. What is a Schematic? Angular CLI Build Serve ✏ Scaffold
7. What is a Schematic? ▪ API to enhance Angular CLI ▪ Adds additional commands.
8. When do we need Schematics? ▪ Scaffold files to match Coding Guidelines ▪ Automatically migrate breaking changes introduced by our own libraries ▪ Simplify setup of 3-party-libraries
9. What benefits bring Schematics? ▪ ⏱ Saves time when ➝ solving recurring developer tasks ➝ setting up 3-party-libraries ➝ migrating to newer library versions ➝ sharing project wide coding guidelines
10. Schematics types ▪ Generate ▪ Add ▪ Update
11. ng generate ng generate component
12. ng add ng add @angular/material
13. ng update ng update @angular/material
14. Project setup npm i --global @angular-devkit/schematics-cli
15. Project setup schematics blank <your-schematics-name>
16. Project structure ▪ Similar to ng new ▪ Everything you need in one place
17. Schematic source ▪ Each schematic lives in its own directory. ▪ Tests are generated automatically.
18. collection.json ▪ Schematics are described in JSON. ▪ Contains ➝ command name ➝ documentation
19. package.json ▪ Schematics are registered in package.json to be discoverable for Angular CLI
20. package.json Register a collection { ... "author": "", "license": "MIT", "schematics": "./src/collection.json" }
21. Define a collection collection.json { "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json", "schematics": { "schematic-a": { ... }, "schematic-b": { ... }, "schematic-c": { ... }, "schematic-d": { ... } } }
22. Define a collection
23. Define a collection collection.json ... "schematic-a": { "aliases": ["a"], "description": "Short description", "factory": "./schematic-a/index#methodName", "schema": "./schematic-a/schema.json", "private": false|true }
24. Define a schema schematic-a/schema.json { "$schema": "http://json-schema.org/schema", "id": "schmatic-a", "title": "schematic title", "type": "object", "description": "schematic description", "properties": { ... }, "required": ["name"] }
25. Schematic parameters schematic-a/schema.json { "properties": { "yourProperty": { "type": "string", "description": "The name of the Component.", "default": "some default", "x-prompt": "What name would you like to use for the Component?" } } }
26. Schematic parameters ng generate lib:yourSchematic \ --yourProperty "override default"
27. Schematic parameters schematic-a/schema.json { "properties": { "yourProperty": { "type": "string", "description": "Short description", "$default": { "$source": "argv", "index": 0 }, "x-prompt": "What name would you like to use for the Component?" } } }
28. Schematic parameters ng generate lib:yourSchematic argv0
29. Define a factory schematic-a/index.ts import { HostTree } from '@angular-devkit/schematics'; export function factory(): Rule { return (tree: HostTree) => { return tree; }; }
30. Define a factory taking parameters schematic-a/index.ts import { HostTree } from '@angular-devkit/schematics'; export function factory(options: any): Rule { return (tree: HostTree) => { return tree; }; } Properties defined in schema.json
31. Relation between collection & schematic index.ts import { Observable } from 'rxjs'; const helloWorld$ = new Observable( function subscribe(observer) { observer.next('Hello'); observer.next('World'); observer.complete(); } ); collection.json "schematic-a": { "aliases": ["f"], "description": "...", "factory": ".../index#factory", "schema": "..../schema.json", } export function factory(): Rule { return (tree: HostTree) => { return tree; }; }
32. Relation between collection & schematic package.json collection.json schema.json factory
33. Task Logging Schematic http://bit.do/wdc-19-schematics
34. https://github.com/ngx-training/angular-schematics-starter
35. HostTree, Tree ▪ Tree → Staging area for changes ▪ Contains ➝ the original file system ➝ a list of changes to apply to tree ➝ Virtual representation of every file in the workspace ▪ Tree is an interface ▪ HostTree implements Tree interface ▪ Provides API for work with file system and changes
36. create() HostTree API Example import { Tree } from '@angular-devkit/schematics'; tree.create(path: string, content: Buffer | string) // Example tree.create('./welcome.txt', 'Welcome to WDC 2018!'); Filename or/with path to file Content to be inserted in the file
37. exists() HostTree API Example import { Tree } from '@angular-devkit/schematics'; tree.exists(path: string): boolean // Example if (tree.exists('./welcome.txt')) { // do something if file existing } Filename or/with path to file
38. overwrite() HostTree API Example import { Tree } from '@angular-devkit/schematics'; tree.overwrite(path: string, content: Buffer | string) // Example tree.overwrite('./welcome.txt', 'Welcome to WDC 2019!'); Path to the file to be overwritten Overwrite with new content
39. beginUpdate() and commitUpdate() HostTree API Example import { Tree } from '@angular-devkit/schematics'; tree.overwrite(path: string, content: Buffer | string) // Example tree.overwrite('./welcome.txt', 'Welcome to WDC 2019!'); Path to the file to be overwritten Overwrite with new content
40. Context ▪ Each schematic runs in a context ▪ Provides access to utility functions and metadata ▪ Including a logging API → Helps with debugging ▪ Defines merge strategy
41. Logging API SchematicContext API Example import { SchematicContext } from '@angular-devkit/schematics'; return (tree: Tree, context: SchematicContext) => { context.logger.info('Hello WDC 2019!'); context.logger.error('Error!'); context.logger.warn('Warning!'); ... return tree; } Define schematic context Write warning message to console
42. Tasks ▪ SchematicContext object allow to run tasks ▪ Usage: context.addTask() ▪ e.g.: NodePackageInstallTask() ▪ e.g.: RunSchematicTask()
43. Task Prettier Schematic http://bit.do/wdc-19-schematics
44. Templates <TEMPLATE> Source factory ng g lib:shecmatic \ --name 'Hi WDC' \ --spec false \ --flat true
45. Template Templates @Component({ selector: <%= selector %>, templateUrl: './<%= kebabCase(name) %>.page.html', }) export class <%= upperFirst(camelCase(name)) %>Page implements OnInit { <% if(routePath) { %>private route: ActivatedRoute <% } %> }
46. Templates ng generate lib:component myCoolWidget upperFirst('myCoolWidget') kebabCase('myCoolWidget’') MyCoolWidget my-cool-widget
47. Pipes
48. Templates @angular-devkit/core strings camelCase dasherize classify ...
49. File operators ▪ Allow loading and transforming file templates. ▪ Create own virtual file streams. ▪ Turn virtual file streams into reality by merging them into host tree.
50. API Demo Load, transform, merge const templates = apply( url('./files'), [ applyTemplates({ ...options, ...strings }) ]); Create a virtual file tree
51. API Demo Load, transform, merge const templates = apply( url('./files'), [ applyTemplates({ ...options, ...strings }) ]); Load templates from path.
52. Factory Load & transform const templates = apply( url('./files'), [ applyTemplates({ ...options, ...strings }) ]); Merge options and pipes into templates
53. Merge into tree Factory export function component(options: ComponentOptions): Rule { return (_host: HostTree) => { const templates = apply(url('./files'), [ applyTemplates({ ...options, ...strings }) ]); return chain([mergeWith(templates)]); }; }
54. Factory Further operators apply(url('./files'), [ applyTemplates({ ...component, ...strings }), move(component.path), forEach(entry => (tree.exists(entry.path) ? null : entry)) ]);
55. Task Component Schematic http://bit.do/wdc-19-schematics
56. ng-add ▪ Automatically add library to project ▪ Download and install dependencies ▪ Invokes installation script
57. ng-add ng add <schematic> Execute install script Download new package version.
58. collection.json Define ng-add collection ... "ng-add": { "aliases": ["install"], "description": "Custom ng-add schematic", "factory": "./ng-add/index", "schema": "./ng-add/schema.json" } ...
59. Relation between collection & schematic index.ts import { Observable } from 'rxjs'; const helloWorld$ = new Observable( function subscribe(observer) { observer.next('Hello'); observer.next('World'); observer.complete(); } ); collection.json ... "ng-add": { "aliases": ["install"], "description": "...", "factory": "./ng-add/index", "schema": "./ng-add/schema.json" } export default function(options: any): Rule { return (tree: Tree,) => { // ... return tree; } }
60. Install helper tools npm install @schematics/angular
61. Helper tools ▪ Add node dependencies to package.json ▪ Interface for node dependency ▪ Enum for node dependency types
62. NodeDependency and NodeDependencyType dependencies.d.ts export interface NodeDependency { type: NodeDependencyType; name: string; version: string; overwrite?: boolean; } dependencies.d.ts export enum NodeDependencyType { Default = "dependencies", Dev = "devDependencies", Peer = "peerDependencies", Optional = "optionalDependencies" }
63. index.ts addPackageJsonDependency() import { addPackageJsonDependency, NodeDependency } from '@schematics/angular/utility/dependencies'; ... function addPackageJsonDependencies(): Rule { return (tree: Tree, context: SchematicContext) => { const dependency: NodeDependency = { ... }; addPackageJsonDependency(tree, dependency); return tree; } }
64. Task ng-add Schematic http://bit.do/wdc-19-schematics
65. ng-update ▪ Automatically do migrations ▪ Apply fixes project wide ▪ Update specific packages
66. ng-update ng update <schematic> Execute update script Download new package version.
67. package.json Register migrations ... "schematics": "./src/collection.json", "ng-update": { "migrations": "./src/migrations.json" } ...
68. migrations.json Define migration { "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json", "schematics": { "migration-v2": { "version": "2.0.0", "description": "Add test file to component", "factory": "./ng-update/index#updateToV2" } } }
69. Relation between migrations & schematic index.ts import { Observable } from 'rxjs'; const helloWorld$ = new Observable( function subscribe(observer) { observer.next('Hello'); observer.next('World'); observer.complete(); } ); migrations.json ... "migration-v2": { "version": "2.0.0", "description": "...", "factory": ".../index#migration", } export function migration(): Rule { return (tree: HostTree) => { // ... return tree; }; }
70. Task ng-update Schematic http://bit.do/wdc-19-schematics
71. Resources ▪ https://mhartington.io/post/angular-schematics-and-dynamic-content/ ▪ https://medium.com/@tomastrajan/total-guide-to-custom-angular-schematics-5c50cf90cdb4 ▪ https://www.youtube.com/watch?v=bnhrLH3bOFo ▪ https://www.youtube.com/watch?v=ZKyz0lb0GjA ▪ https://unsplash.com ▪ https://flaticon.com
72. Assets | Code hello-world.ts hello-world.ts import { Observable } from 'rxjs'; const helloWorld$ = new Observable( function subscribe(observer) { observer.next('Hello'); observer.next('World'); observer.complete(); } ); // ... const observer = { next: (value) => console.log(value), error: (err) => console.error(err), complete: () => console.log('done') }; const subscription = helloWorld$.subscribe(observer);
73. Assets | Code API Demo