A scaffolding library for the modern web.
Schematics are generators that transform an existing filesystem. It can create files, refactor existing files, or move files around.
What distinguish 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||A generator that execute descriptive code without side effects on an existing file system.|
|Collection||A list of schematics metadata. Schematics can be referred by name inside a collection.|
|Tool||The code using the Schematics library.|
|Tree||A staging area for changes, containing the original file system, and a list of changes to apply to it.|
|Rule||A function that applies actions to a
|Source||A function that creates an entirely new
|Action||A atomic operation to be validated and committed to a filesystem or a
|Sink||The final destination of all
Schematics is a library, and does not work by itself. A reference CLI is available on this repository, but is not published on NPM. This document explain the library usage and the tooling API, but does not go into the tool implementation itself.
The tooling is responsible for the following tasks:
The tooling API is composed of the following pieces:
SchematicEngine is responsible for loading and constructing
Schematics'. When creating an engine, the tooling provides an
EngineHost interface that understands how to create a
CollectionDescription from a name, and how to create a
Schematics are generators and part of a
A Collection is defined by a
collection.json file (in the reference CLI). This JSON defines the following properties:
||The name of the collection.|
Source is a generator of
Tree; it creates a root tree from nothing. A
Rule is a transformation from one
Tree to another. A
Schematic (at the root) is a
Rule that is normally applied on the filesystem.
FileOperators apply changes to a single
FileEntry and return a new
FileEntry. The result follows these rules:
FileEntryreturned is null, a
DeleteActionwill be added to the action list.
RenameActionwill be added to the action list.
OverwriteActionwill be added to the action list.
It is impossible to create files using a
||Apply a content template (see the Template section)|
||Apply a path template (see the Template section)|
The Schematics library provides multiple
Source factories by default that cover basic use cases:
||Creates a source that returns the tree passed in argument.|
||Creates a source that returns an empty tree.|
||Apply a list of rules to a source, and return the result.|
||Loads a list of files from a URL and returns a Tree with the files as
The schematics library also provides
Rule factories by default:
||Returns the input
||Moves all the files from the input to a subdirectory.|
||Merge the input
||Apply a content template (see the Template section) to the entire
||Apply a path template (see the Template section) to the entire
||Apply both path and content templates (see the Template section) to the entire
||Returns the input
An example of a simple Schematics which creates a "hello world" file, using an option to determine its path:
A few things from this example:
Rule, which is a transformation from a
Schematics is not done yet. Here's a list of things we are considering: