When you create an Angular library, you can provide and package it with schematics that integrate it with the Angular CLI.\nWith your schematics, your users can use ng add to install an initial version of your library,\nng generate to create artifacts defined in your library, and ng update to adjust their project for a new version of your library that introduces breaking changes.
All three types of schematics can be part of a collection that you package with your library.
\nDownload the
To start a collection, you need to create the schematic files.\nThe following steps show you how to add initial support without modifying any project files.
\nIn your library's root folder, create a schematics/ folder.
In the schematics/ folder, create an ng-add/ folder for your first schematic.
At the root level of the schematics/ folder, create a collection.json file.
Edit the collection.json file to define the initial schema for your collection.
$schema path is relative to the Angular Devkit collection schema.schematics object describes the named schematics that are part of this collection.ng-add. It contains the description, and points to the factory function that is called when your schematic is executed.package.json file, add a \"schematics\" entry with the path to your schema file.\nThe Angular CLI uses this entry to find named schematics in your collection when it runs commands.The initial schema that you have created tells the CLI where to find the schematic that supports the ng add command.\nNow you are ready to create that schematic.
A schematic for the ng add command can enhance the initial installation process for your users.\nThe following steps will define this type of schematic.
Go to the
Create the main file, index.ts.
Open index.ts and add the source code for your schematic factory function.
The only step needed to provide initial ng add support is to trigger an installation task using the SchematicContext.\nThe 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.
In this example, the function receives the current Tree and returns it without any modifications.\nIf you need to, you can do additional setup when your package is installed, such as generating files, updating configuration, or any other initial setup your library requires.
Use the save option of ng-add to configure if the library should be added to the dependencies, the devDepedencies, or not saved at all in the project's package.json configuration file.
Possible values are:
\nfalse - Don't add the package to package.jsontrue - Add the package to the dependencies\"dependencies\" - Add the package to the dependencies\"devDependencies\" - Add the package to the devDependenciesTo bundle your schematics together with your library, you must configure the library to build the schematics separately, then add them to the bundle.\nYou must build your schematics after you build your library, so they are placed in the correct directory.
\nYour library needs a custom Typescript configuration file with instructions on how to compile your schematics into your distributed library.
\nTo add the schematics to the library bundle, add scripts to the library's package.json file.
Assume you have a library project my-lib in your Angular workspace.\nTo tell the library how to build the schematics, add a tsconfig.schematics.json file next to the generated tsconfig.lib.json file that configures the library build.
tsconfig.schematics.json file to add the following content.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.
package.json file in your library project's root folder (projects/my-lib).build script compiles your schematic using the custom tsconfig.schematics.json file.copy:* statements copy compiled schematic files into the proper locations in the library output folder in order to preserve the file structure.postbuild script copies the schematic files after the build script completes.You can add a named schematic to your collection that lets your users use the ng generate command to create an artifact that is defined in your library.
We'll assume that your library defines a service, my-service, that requires some setup. You want your users to be able to generate it using the following CLI command.
To begin, create a new subfolder, my-service, in the schematics folder.
When you add a schematic to the collection, you have to point to it in the collection's schema, and provide configuration files to define options that a user can pass to the command.
\nschematics/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.Go to the <lib-root>/schematics/my-service/ folder.
Create a schema.json file and define the available options for the schematic.
id: A unique id for the schema in the collection.
\ntitle: A human-readable description of the schema.
\ntype: A descriptor for the type provided by the properties.
\nproperties: An object that defines the available options for the schematic.
\nEach option associates key with a type, description, and optional alias.\nThe type defines the shape of the value you expect, and the description is displayed when the user requests usage help for your schematic.
\nSee the workspace schema for additional customizations for schematic options.
\nschema.ts file and define an interface that stores the values of the options defined in the schema.json file.To add artifacts to a project, your schematic needs its own template files.\nSchematic templates support special syntax to execute code and variable substitution.
\nCreate a files/ folder inside the schematics/my-service/ folder.
Create a file named __name@dasherize__.service.ts.template that defines a template you can use for generating files. This template will generate a service that already has Angular's HttpClient injected into its constructor.
The classify and dasherize methods are utility functions that your schematic will use to transform your source template and filename.
The name is provided as a property from your factory function. It is the same name you defined in the schema.
Now that you have the infrastructure in place, you can define the main function that performs the modifications you need in the user's project.
\nThe Schematics framework provides a file templating system, which supports both path and content templates.\nThe system operates on placeholders defined inside files or paths that loaded in the input Tree.\nIt fills these in using values passed into the Rule.
For details of these data structures and syntax, see the Schematics README.
\nCreate the main file index.ts and add the source code for your schematic factory function.
First, import the schematics definitions you will need. The Schematics framework offers many utility functions to create and use rules when running a schematic.
\nThis simple rule factory returns the tree without modification.\nThe options are the option values passed through from the ng generate command.
We now have the framework in place for creating the code that actually modifies the user's application to set it up for the service defined in your library.
\nThe Angular workspace where the user has installed your library contains multiple projects (applications and libraries).\nThe user can specify the project on the command line, or allow it to default.\nIn either case, your code needs to identify the specific project to which this schematic is being applied, so that you can retrieve information from the project configuration.
\nYou can do this using the Tree object that is passed in to the factory function.\nThe Tree methods give you access to the complete file tree in your workspace, allowing you to read and write files during the execution of the schematic.
workspaces.readWorkspace method to read the contents of the workspace configuration file, angular.json.\nTo use workspaces.readWorkspace you need to create a workspaces.WorkspaceHost from the Tree.\nAdd the following code to your factory function.WorkspaceDefinition, extensions property includes a defaultProject value for determining which project to use if not provided.\nWe will use that value as a fallback, if no project is explicitly specified in the ng generate command. The workspace projects object contains all the project-specific configuration information.
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.\nIf the path is not defined, use the sourceRoot from the project configuration along with the projectType.
A Rule can use external template files, transform them, and return another Rule object with the transformed template. You can use the templating to generate any custom files required for your schematic.
apply() method applies multiple rules to a source and returns the transformed source. It takes 2 arguments, a source and an array of rules.url() method reads source files from your filesystem, relative to the schematic.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.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 MyServicedasherize() 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.move method moves the provided source files to their destination when the schematic is applied. The chain() method allows you to combine multiple rules into a single rule, so that you can perform multiple operations in a single schematic.\nHere you are only merging the template rules with any code executed by the schematic.
See a complete exampled of the schematic rule function.
\nFor more information about rules and utility methods, see Provided Rules.
\nAfter you build your library and schematics, you can install the schematics collection to run against your project. The steps below show you how to generate a service using the schematic you created above.
\nFrom the root of your workspace, run the ng build command for your library.
Then, you change into your library directory to build the schematic
\nYour library and schematics are packaged and placed in the dist/my-lib folder at the root of your workspace. For running the schematic, you need to link the library into your node_modules folder. From the root of your workspace, run the npm link command with the path to your distributable library.
Now that your library is installed, you can run the schematic using the ng generate command.
In the console, you will see that the schematic was run and the my-data.service.ts file was created in your app folder.