docs: add schematics guide (angular#28343)

PR Close angular#28343

Author: jbogarthyde

aio/content/examples/.gitignore

@@ -92,3 +92,6 @@ upgrade-phonecat-3-final/tsconfig-aot.json
 upgrade-phonecat-3-final/rollup-config.js
 !upgrade-phonecat-*/**/karma.conf.js
 !upgrade-phonecat-*/**/karma-test-shim.js
+
+# schematics
+!schematics-for-libraries/projects/my-lib/package.json

aio/content/examples/schematics-for-libraries/example-config.json

@@ -0,0 +1,3 @@
+{
+  "projectType": "schematics"
+}

aio/content/examples/schematics-for-libraries/projects/my-lib/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/my-lib",
+  "lib": {
+    "entryFile": "src/public_api.ts"
+  }
+}

aio/content/examples/schematics-for-libraries/projects/my-lib/package.json

@@ -0,0 +1,20 @@
+// #docplaster
+// #docregion collection
+{
+  "name": "my-lib",
+  "version": "0.0.1",
+// #enddocregion collection
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -p tsconfig.schematics.json",
+    "copy:schemas": "cp --parents schematics/*/schema.json ../../dist/my-lib/",
+    "copy:files": "cp --parents -p schematics/*/files/** ../../dist/my-lib/",
+    "copy:collection": "cp schematics/collection.json ../../dist/my-lib/schematics/collection.json",
+    "postbuild": "npm run copy:schemas && npm run copy:files && npm run copy:collection"
+  },
+  "peerDependencies": {
+    "@angular/common": "^7.2.0",
+    "@angular/core": "^7.2.0"
+  },
+// #docregion collection
+  "schematics": "./schematics/collection.json"
+}

aio/content/examples/schematics-for-libraries/projects/my-lib/schematics/collection.1.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
+  "schematics": {
+    "ng-add": {
+      "description": "Add my library to the project.",
+      "factory": "./ng-add/index#ngAdd"
+    }
+  }
+}

aio/content/examples/schematics-for-libraries/projects/my-lib/schematics/collection.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
+  "schematics": {
+    "ng-add": {
+      "description": "Add my library to the project.",
+      "factory": "./ng-add/index#ngAdd"
+    },
+    "my-service": {
+      "description": "Generate a service in the project.",
+      "factory": "./my-service/index#myService",
+      "schema": "./my-service/schema.json"
+    }
+  }
+}

aio/content/examples/schematics-for-libraries/projects/my-lib/schematics/my-service/files/__name@dasherize__.service.ts.template

@@ -0,0 +1,10 @@
+// #docregion template
+import { Injectable } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class <%= classify(name) %>Service {
+  constructor(private http: HttpClient) { }
+}

aio/content/examples/schematics-for-libraries/projects/my-lib/schematics/my-service/index.1.ts

@@ -0,0 +1,11 @@
+import { Rule, Tree } from '@angular-devkit/schematics';
+
+import { Schema as MyServiceSchema } from './schema';
+
+// #docregion factory
+export function myService(options: MyServiceSchema): Rule {
+  return (tree: Tree) => {
+    return tree;
+  };
+}
+// #enddocregion factory

aio/content/examples/schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts

@@ -0,0 +1,66 @@
+// #docplaster
+// #docregion schematics-imports, schema-imports, workspace
+import {
+  Rule, Tree, SchematicsException,
+  apply, url, applyTemplates, move,
+  chain, mergeWith
+} from '@angular-devkit/schematics';
+
+import { strings, normalize, experimental } from '@angular-devkit/core';
+// #enddocregion schematics-imports
+
+import { Schema as MyServiceSchema } from './schema';
+// #enddocregion schema-imports
+
+export function myService(options: MyServiceSchema): Rule {
+  return (tree: Tree) => {
+    const workspaceConfig = tree.read('/angular.json');
+    if (!workspaceConfig) {
+      throw new SchematicsException('Could not find Angular workspace configuration');
+    }
+
+    // convert workspace to string
+    const workspaceContent = workspaceConfig.toString();
+
+    // parse workspace string into JSON object
+    const workspace: experimental.workspace.WorkspaceSchema = JSON.parse(workspaceContent);
+// #enddocregion workspace
+// #docregion project-fallback
+    if (!options.project) {
+      options.project = workspace.defaultProject;
+    }
+// #enddocregion project-fallback
+
+// #docregion project-info
+    const projectName = options.project as string;
+
+    const project = workspace.projects[projectName];
+
+    const projectType = project.projectType === 'application' ? 'app' : 'lib';
+// #enddocregion project-info
+
+// #docregion path
+    if (options.path === undefined) {
+      options.path = `${project.sourceRoot}/${projectType}`;
+    }
+// #enddocregion path
+
+// #docregion template
+    const templateSource = apply(url('./files'), [
+      applyTemplates({
+        classify: strings.classify,
+        dasherize: strings.dasherize,
+        name: options.name
+      }),
+      move(normalize(options.path as string))
+    ]);
+// #enddocregion template
+
+// #docregion chain
+    return chain([
+      mergeWith(templateSource)
+    ]);
+// #enddocregion chain
+// #docregion workspace
+  };
+}

aio/content/examples/schematics-for-libraries/projects/my-lib/schematics/my-service/schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "id": "SchematicsMyService",
+  "title": "My Service Schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "description": "The name of the service.",
+      "type": "string"
+    },
+    "path": {
+      "type": "string",
+      "format": "path",
+      "description": "The path to create the service.",
+      "visible": false
+    },
+    "project": {
+      "type": "string",
+      "description": "The name of the project.",
+      "$default": {
+        "$source": "projectName"
+      }
+    }
+   },
+  "required": [
+    "name"
+  ]
+}