docs: ident the library shematics guide properly (#41755)
PR Close #41755
This commit is contained in:
Aristeidis Bampakos
Jessica Janiuk
parent
122c8ba0e3
commit
dfdd4a2d74
@ -21,18 +21,18 @@ The following steps show you how to add initial support without modifying any pr
|
||||
|
||||
1. Edit the `collection.json` file to define the initial schema for your collection.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/collection.json (Schematics Collection)" path="schematics-for-libraries/projects/my-lib/schematics/collection.1.json">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/collection.json (Schematics Collection)" path="schematics-for-libraries/projects/my-lib/schematics/collection.1.json">
|
||||
</code-example>
|
||||
|
||||
* The `$schema` path is relative to the Angular Devkit collection schema.
|
||||
* The `schematics` object describes the named schematics that are part of this collection.
|
||||
* The first entry is for a schematic named `ng-add`. It contains the description, and points to the factory function that is called when your schematic is executed.
|
||||
* The `$schema` path is relative to the Angular Devkit collection schema.
|
||||
* The `schematics` object describes the named schematics that are part of this collection.
|
||||
* The first entry is for a schematic named `ng-add`. It contains the description, and points to the factory function that is called when your schematic is executed.
|
||||
|
||||
1. In your library project's `package.json` file, add a "schematics" entry with the path to your schema file.
|
||||
The Angular CLI uses this entry to find named schematics in your collection when it runs commands.
|
||||
|
||||
<code-example header="projects/my-lib/package.json (Schematics Collection Reference)" path="schematics-for-libraries/projects/my-lib/package.json" region="collection">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/package.json (Schematics Collection Reference)" path="schematics-for-libraries/projects/my-lib/package.json" region="collection">
|
||||
</code-example>
|
||||
|
||||
The initial schema that you have created tells the CLI where to find the schematic that supports the `ng add` command.
|
||||
Now you are ready to create that schematic.
|
||||
@ -48,8 +48,8 @@ The following steps will define this type of schematic.
|
||||
|
||||
1. Open `index.ts` and add the source code for your schematic factory function.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/ng-add/index.ts (ng-add Rule Factory)" path="schematics-for-libraries/projects/my-lib/schematics/ng-add/index.ts">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/ng-add/index.ts (ng-add Rule Factory)" path="schematics-for-libraries/projects/my-lib/schematics/ng-add/index.ts">
|
||||
</code-example>
|
||||
|
||||
The only step needed to provide initial `ng add` support is to trigger an installation task using the `SchematicContext`.
|
||||
The task uses the user's preferred package manager to add the library to the project's `package.json` configuration file, and install it in the project’s `node_modules` directory.
|
||||
@ -85,21 +85,21 @@ To tell the library how to build the schematics, add a `tsconfig.schematics.json
|
||||
|
||||
1. Edit the `tsconfig.schematics.json` file to add the following content.
|
||||
|
||||
<code-example header="projects/my-lib/tsconfig.schematics.json (TypeScript Config)" path="schematics-for-libraries/projects/my-lib/tsconfig.schematics.json">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/tsconfig.schematics.json (TypeScript Config)" path="schematics-for-libraries/projects/my-lib/tsconfig.schematics.json">
|
||||
</code-example>
|
||||
|
||||
* The `rootDir` specifies that your `schematics/` folder contains the input files to be compiled.
|
||||
* The `rootDir` specifies that your `schematics/` folder contains the input files to be compiled.
|
||||
|
||||
* The `outDir` maps to the library's output folder. By default, this is the `dist/my-lib` folder at the root of your workspace.
|
||||
* The `outDir` maps to the library's output folder. By default, this is the `dist/my-lib` folder at the root of your workspace.
|
||||
|
||||
1. To make sure your schematics source files get compiled into the library bundle, add the following scripts to the `package.json` file in your library project's root folder (`projects/my-lib`).
|
||||
|
||||
<code-example header="projects/my-lib/package.json (Build Scripts)" path="schematics-for-libraries/projects/my-lib/package.json">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/package.json (Build Scripts)" path="schematics-for-libraries/projects/my-lib/package.json">
|
||||
</code-example>
|
||||
|
||||
* The `build` script compiles your schematic using the custom `tsconfig.schematics.json` file.
|
||||
* The `copy:*` statements copy compiled schematic files into the proper locations in the library output folder in order to preserve the file structure.
|
||||
* The `postbuild` script copies the schematic files after the `build` script completes.
|
||||
* The `build` script compiles your schematic using the custom `tsconfig.schematics.json` file.
|
||||
* The `copy:*` statements copy compiled schematic files into the proper locations in the library output folder in order to preserve the file structure.
|
||||
* The `postbuild` script copies the schematic files after the `build` script completes.
|
||||
|
||||
## Providing generation support
|
||||
|
||||
@ -119,20 +119,20 @@ When you add a schematic to the collection, you have to point to it in the colle
|
||||
|
||||
1. Edit the `schematics/collection.json` file to point to the new schematic subfolder, and include a pointer to a schema file that will specify inputs for the new schematic.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/collection.json (Schematics Collection)" path="schematics-for-libraries/projects/my-lib/schematics/collection.json">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/collection.json (Schematics Collection)" path="schematics-for-libraries/projects/my-lib/schematics/collection.json">
|
||||
</code-example>
|
||||
|
||||
1. Go to the `<lib-root>/schematics/my-service/` folder.
|
||||
|
||||
1. Create a `schema.json` file and define the available options for the schematic.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/schema.json (Schematic JSON Schema)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/schema.json">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/my-service/schema.json (Schematic JSON Schema)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/schema.json">
|
||||
</code-example>
|
||||
|
||||
* *id*: A unique id for the schema in the collection.
|
||||
* *title*: A human-readable description of the schema.
|
||||
* *type*: A descriptor for the type provided by the properties.
|
||||
* *properties*: An object that defines the available options for the schematic.
|
||||
* *id*: A unique id for the schema in the collection.
|
||||
* *title*: A human-readable description of the schema.
|
||||
* *type*: A descriptor for the type provided by the properties.
|
||||
* *properties*: An object that defines the available options for the schematic.
|
||||
|
||||
Each option associates key with a type, description, and optional alias.
|
||||
The type defines the shape of the value you expect, and the description is displayed when the user requests usage help for your schematic.
|
||||
@ -141,12 +141,12 @@ When you add a schematic to the collection, you have to point to it in the colle
|
||||
|
||||
1. Create a `schema.ts` file and define an interface that stores the values of the options defined in the `schema.json` file.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/schema.ts (Schematic Interface)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/schema.ts">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/my-service/schema.ts (Schematic Interface)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/schema.ts">
|
||||
</code-example>
|
||||
|
||||
* *name*: The name you want to provide for the created service.
|
||||
* *path*: Overrides the path provided to the schematic. The default path value is based on the current working directory.
|
||||
* *project*: Provides a specific project to run the schematic on. In the schematic, you can provide a default if the option is not provided by the user.
|
||||
* *name*: The name you want to provide for the created service.
|
||||
* *path*: Overrides the path provided to the schematic. The default path value is based on the current working directory.
|
||||
* *project*: Provides a specific project to run the schematic on. In the schematic, you can provide a default if the option is not provided by the user.
|
||||
|
||||
### Add template files
|
||||
|
||||
@ -189,18 +189,18 @@ For details of these data structures and syntax, see the [Schematics README](htt
|
||||
|
||||
1. First, import the schematics definitions you will need. The Schematics framework offers many utility functions to create and use rules when running a schematic.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Imports)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="schematics-imports">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Imports)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="schematics-imports">
|
||||
</code-example>
|
||||
|
||||
1. Import the defined schema interface that provides the type information for your schematic's options.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Schema Import)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="schema-imports">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Schema Import)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="schema-imports">
|
||||
</code-example>
|
||||
|
||||
1. To build up the generation schematic, start with an empty rule factory.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Initial Rule)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.1.ts" region="factory">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Initial Rule)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.1.ts" region="factory">
|
||||
</code-example>
|
||||
|
||||
This rule factory returns the tree without modification.
|
||||
The options are the option values passed through from the `ng generate` command.
|
||||
@ -222,31 +222,31 @@ The `Tree` methods give you access to the complete file tree in your workspace,
|
||||
To use `workspaces.readWorkspace` you need to create a `workspaces.WorkspaceHost` from the `Tree`.
|
||||
Add the following code to your factory function.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Schema Import)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="workspace">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Schema Import)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="workspace">
|
||||
</code-example>
|
||||
|
||||
* Be sure to check that the context exists and throw the appropriate error.
|
||||
Be sure to check that the context exists and throw the appropriate error.
|
||||
|
||||
1. The `WorkspaceDefinition`, `extensions` property includes a `defaultProject` value for determining which project to use if not provided.
|
||||
1. The `workspace.extensions` property includes a `defaultProject` value for determining which project to use if not provided.
|
||||
We will use that value as a fallback, if no project is explicitly specified in the `ng generate` command.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Default Project)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="project-fallback">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Default Project)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="project-fallback">
|
||||
</code-example>
|
||||
|
||||
1. Now that you have the project name, use it to retrieve the project-specific configuration information.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Project)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="project-info">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Project)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="project-info">
|
||||
</code-example>
|
||||
|
||||
The `workspace projects` object contains all the project-specific configuration information.
|
||||
The `workspace.projects` object contains all the project-specific configuration information.
|
||||
|
||||
1. The `options.path` determines where the schematic template files are moved to once the schematic is applied.
|
||||
|
||||
The `path` option in the schematic's schema is substituted by default with the current working directory.
|
||||
If the `path` is not defined, use the `sourceRoot` from the project configuration along with the `projectType`.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Project Info)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="path">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Project Info)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="path">
|
||||
</code-example>
|
||||
|
||||
### Define the rule
|
||||
|
||||
@ -254,25 +254,25 @@ A `Rule` can use external template files, transform them, and return another `Ru
|
||||
|
||||
1. Add the following code to your factory function.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Template transform)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="template">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Template transform)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="template">
|
||||
</code-example>
|
||||
|
||||
* The `apply()` method applies multiple rules to a source and returns the transformed source. It takes 2 arguments, a source and an array of rules.
|
||||
* The `url()` method reads source files from your filesystem, relative to the schematic.
|
||||
* The `applyTemplates()` method receives an argument of methods and properties you want make available to the schematic template and the schematic filenames. It returns a `Rule`. This is where you define the `classify()` and `dasherize()` methods, and the `name` property.
|
||||
* The `classify()` method takes a value and returns the value in title case. For example, if the provided name is `my service`, it is returned as `MyService`
|
||||
* The `dasherize()` method takes a value and returns the value in dashed and lowercase. For example, if the provided name is MyService, it is returned as `my-service`.
|
||||
* The `move` method moves the provided source files to their destination when the schematic is applied.
|
||||
* The `apply()` method applies multiple rules to a source and returns the transformed source. It takes 2 arguments, a source and an array of rules.
|
||||
* The `url()` method reads source files from your filesystem, relative to the schematic.
|
||||
* The `applyTemplates()` method receives an argument of methods and properties you want make available to the schematic template and the schematic filenames. It returns a `Rule`. This is where you define the `classify()` and `dasherize()` methods, and the `name` property.
|
||||
* The `classify()` method takes a value and returns the value in title case. For example, if the provided name is `my service`, it is returned as `MyService`
|
||||
* The `dasherize()` method takes a value and returns the value in dashed and lowercase. For example, if the provided name is MyService, it is returned as `my-service`.
|
||||
* The `move` method moves the provided source files to their destination when the schematic is applied.
|
||||
|
||||
1. Finally, the rule factory must return a rule.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Chain Rule)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="chain">
|
||||
</code-example>
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts (Chain Rule)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="chain">
|
||||
</code-example>
|
||||
|
||||
The `chain()` method allows you to combine multiple rules into a single rule, so that you can perform multiple operations in a single schematic.
|
||||
Here you are only merging the template rules with any code executed by the schematic.
|
||||
The `chain()` method allows you to combine multiple rules into a single rule, so that you can perform multiple operations in a single schematic.
|
||||
Here you are only merging the template rules with any code executed by the schematic.
|
||||
|
||||
See a complete exampled of the schematic rule function.
|
||||
See a complete example of the schematic rule function below.
|
||||
|
||||
<code-example header="projects/my-lib/schematics/my-service/index.ts" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts">
|
||||
</code-example>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user