Repository files navigation

This repository is a snapshot of a commit on the original repository. The original code used togenerate this is located athttp://github.com/angular/angular-cli.

We do not accept PRs or Issues opened on this repository. You should not use this over a tested andreleased version of this package.

To test this snapshot in your own project, use

npm install git+https://github.com/angular/angular-devkit-schematics-builds.git

A scaffolding library for the modern web.

Schematics are generators that transform an existing filesystem. They can create files, refactor existing files, or move files around.

What distinguishes Schematics from other generators, such as Yeoman or Yarn Create, is that schematics are purely descriptive; no changes are applied to the actual filesystem until everything is ready to be committed. There is no side effect, by design, in Schematics.

Schematics is a library, and does not work by itself. Areference CLI is available on this repository, and is published on NPM at@angular-devkit/schematics-cli. This document explains the library usage and the tooling API, but does not go into the tool implementation itself.

The tooling is responsible for the following tasks:

1. Create the Schematic Engine, and pass in a Collection and Schematic loader.
2. Understand and respect the Schematics metadata and dependencies between collections. Schematics can refer to dependencies, and it's the responsibility of the tool to honor those dependencies. The reference CLI uses NPM packages for its collections.
3. Create the Options object. Options can be anything, but the schematics can specify a JSON Schema that should be respected. The reference CLI, for example, parses the arguments as a JSON object and validates it with the Schema specified by the collection.
4. Schematics provides some JSON Schema formats for validation that tooling should add. These validate paths, html selectors and app names. Please check the reference CLI for how these can be added.
5. Call the schematics with the original Tree. The tree should represent the initial state of the filesystem. The reference CLI uses the current directory for this.
6. Create a Sink and commit the result of the schematics to the Sink. Many sinks are provided by the library; FileSystemSink and DryRunSink are examples.
7. Output any logs propagated by the library, including debugging information.

The tooling API is composed of the following pieces:

TheSchematicEngine is responsible for loading and constructingCollections andSchematics. When creating an engine, the tooling provides anEngineHost interface that understands how to create aCollectionDescription from a name, and how to create aSchematicDescription.

Schematics are generators and part of aCollection.

A Collection is defined by acollection.json file (in the reference CLI). This JSON defines the following properties:

ASource is a generator of aTree; it creates an entirely new root tree from nothing. ARule is a transformation from oneTree to another. ASchematic (at the root) is aRule that is normally applied on the filesystem.

FileOperators apply changes to a singleFileEntry and return a newFileEntry. The result follows these rules:

1. If theFileEntry returned is null, aDeleteAction will be added to the action list.
2. If the path changed, aRenameAction will be added to the action list.
3. If the content changed, anOverwriteAction will be added to the action list.

It is impossible to create files using aFileOperator.

The Schematics library provides multipleOperator factories by default that cover basic use cases:

The Schematics library additionally provides multipleSource factories by default:

The schematics library also providesRule factories by default:

As referenced above, some functions are based upon a file templating system, which consists of path and content templating.

The system operates on placeholders defined inside files or their paths as loaded in theTree and fills these in as defined in the following, using values passed into theRule which applies the templating (i.e.template<T>(options: T)).

An example of a simple Schematics which creates a "hello world" file, using an option to determine its path:

import{Tree}from'@angular-devkit/schematics';exportdefaultfunctionMySchematic(options:any){return(tree:Tree)=>{tree.create(options.path+'/hi','Hello world!');returntree;};}

A few things from this example:

1. The function receives the list of options from the tooling.
2. It returns aRule, which is a transformation from aTree to anotherTree.

A simplified example of a Schematics which creates a file containing a new Class, using an option to determine its name:

// files/__name@dasherize__.tsexportclass<%=classify(name)%>{}

// index.tsimport{strings}from'@angular-devkit/core';import{Rule,SchematicContext,SchematicsException,Tree,apply,branchAndMerge,mergeWith,template,url,}from'@angular-devkit/schematics';import{SchemaasClassOptions}from'./schema';exportdefaultfunction(options:ClassOptions):Rule{return(tree:Tree,context:SchematicContext)=>{if(!options.name){thrownewSchematicsException('Option (name) is required.');}consttemplateSource=apply(url('./files'),[template({        ...strings,        ...options,}),]);returnbranchAndMerge(mergeWith(templateSource));};}

Additional things from this example:

1. strings provides the useddasherize andclassify functions, among others.
2. The files are on-disk in the same root directory as theindex.ts and loaded into aTree.
3. Then thetemplateRule fills in the specified templating placeholders. For this, it only knows about the variables and functions passed to it via the options-object.
4. Finally, the resultingTree, containing the new file, is merged with the existing files of the project which the Schematic is run on.