Schematics

A scaffolding library for the modern web.

Description

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.

Glossary

Tooling

Schematics is a library, and does not work by itself. A reference 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:

Engine

The SchematicEngine is responsible for loading and constructing Collections and 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 SchematicDescription.

Schematics (Generators)

Schematics are generators and part of a Collection.

Collection

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

Schematic

Operators, Sources and Rules

A Source is a generator of a Tree; it creates an entirely new 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.

Operators

FileOperators apply changes to a single FileEntry and return a new FileEntry. The result follows these rules:

1. If the FileEntry returned is null, a DeleteAction will be added to the action list.
2. If the path changed, a RenameAction will be added to the action list.
3. If the content changed, an OverwriteAction will be added to the action list.

It is impossible to create files using a FileOperator.

Provided Operators

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

Provided Sources

The Schematics library additionally provides multiple Source factories by default:

Provided Rules

The schematics library also provides Rule factories by default:

Templating

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 the Tree and fills these in as defined in the following, using values passed into the Rule which applies the templating (i.e. template<T>(options: T)).

Path Templating

Content Templating

Examples

Simple

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';

export default function MySchematic(options: any) {
  return (tree: Tree) => {
    tree.create(options.path + '/hi', 'Hello world!');
    return tree;
  };
}

A few things from this example:

1. The function receives the list of options from the tooling.
2. It returns a Rule, which is a transformation from a Tree to another Tree.

Templating

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

// files/__name@dasherize__.ts

export class <%= classify(name) %> {
}

// index.ts

import { strings } from '@angular-devkit/core';
import {
  Rule,
  SchematicContext,
  SchematicsException,
  Tree,
  apply,
  branchAndMerge,
  mergeWith,
  template,
  url,
} from '@angular-devkit/schematics';
import { Schema as ClassOptions } from './schema';

export default function (options: ClassOptions): Rule {
  return (tree: Tree, context: SchematicContext) => {
    if (!options.name) {
      throw new SchematicsException('Option (name) is required.');
    }

    const templateSource = apply(url('./files'), [
      template({
        ...strings,
        ...options,
      }),
    ]);

    return branchAndMerge(mergeWith(templateSource));
  };
}

Additional things from this example:

1. strings provides the used dasherize and classify functions, among others.
2. The files are on-disk in the same root directory as the index.ts and loaded into a Tree.
3. Then the template Rule 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 resulting Tree, containing the new file, is merged with the existing files of the project which the Schematic is run on.

19.1.3 (2025-01-20)

@angular/build

19.1.2 (2025-01-17)

@angular/build

19.1.1 (2025-01-16)

@angular/build

19.1.0 (2025-01-15)

Deprecations

@angular/build

• The baseHref option under i18n.locales and i18n.sourceLocale in angular.json is deprecated in favor of subPath.

  The subPath defines the URL segment for the locale, serving as both the HTML base HREF and the directory name for output. By default, if not specified, subPath will use the locale code.

@schematics/angular

@angular-devkit/architect

@angular-devkit/core

@angular-devkit/schematics

@angular/build

@angular/ssr

19.0.7 (2025-01-08)

@angular-devkit/architect

@angular-devkit/build-angular

@angular/build

19.0.6 (2024-12-18)

@angular-devkit/build-angular

@angular/build

@angular/ssr

19.0.5 (2024-12-12)

@angular-devkit/build-angular

@angular/build

@angular/ssr

19.0.4 (2024-12-05)

@angular-devkit/build-angular

@angular/build

19.0.3 (2024-12-04)

@angular/cli

@schematics/angular

@angular/build

@angular/ssr

19.0.2 (2024-11-25)

@schematics/angular

@angular/build

@angular/ssr

19.0.1 (2024-11-21)

@angular-devkit/build-angular

@angular/build

@angular/ssr

19.0.0 (2024-11-19)

Breaking Changes

@schematics/angular

• The app-shell schematic is no longer compatible with Webpack-based builders.

@angular-devkit/build-angular

• The browserTarget option has been removed from the DevServer and ExtractI18n builders. buildTarget is to be used instead.

• Protractor is no longer supported.

  Protractor was marked end-of-life in August 2023 (see https://protractortest.org/). Projects still relying on Protractor should consider migrating to another E2E testing framework, several support solid migration paths from Protractor.

  • https://angular.dev/tools/cli/end-to-end
  • https://blog.angular.dev/the-state-of-end-to-end-testing-with-angular-d175f751cb9c

@angular-devkit/core

• The deprecated fileBuffer function is no longer available. Update your code to use stringToFileBuffer instead to maintain compatibility.

  Note: that this change does not affect application developers.

@angular/build

• The @angular/localize/init polyfill will no longer be added automatically to projects. To prevent runtime issues, ensure that this polyfill is manually included in the "polyfills" section of your "angular.json" file if your application relies on Angular localization features.

@angular/ssr

• The CommonEngine API now needs to be imported from @angular/ssr/node.

  Before

  import { CommonEngine } from '@angular/ssr';

  After

  import { CommonEngine } from '@angular/ssr/node';

@angular-devkit/schematics-cli

@schematics/angular

@angular/cli

@angular-devkit/architect

@angular-devkit/build-angular

@angular-devkit/core

@angular/build

@angular/ssr

18.2.12 (2024-11-14)

@angular/cli

@angular/build

18.2.11 (2024-10-30)

@angular/build

18.2.10 (2024-10-23)

@angular-devkit/build-angular

@angular/build

17.3.11 (2024-10-23)

@angular-devkit/build-angular

18.2.9 (2024-10-16)

@schematics/angular

@angular/build

18.2.8 (2024-10-09)

@schematics/angular

@angular/build

18.2.7 (2024-10-02)

@schematics/angular

@angular/build

18.2.6 (2024-09-25)

@angular/build

17.3.10 (2024-09-25)

@angular-devkit/build-angular

18.2.5 (2024-09-18)

@angular/build

16.2.16 (2024-09-18)

@angular-devkit/build-angular

18.2.4 (2024-09-11)

@angular/build

18.2.3 (2024-09-04)

@angular-devkit/build-angular

18.2.2 (2024-08-29)

@angular-devkit/build-angular

17.3.9 (2024-08-29)

@angular-devkit/build-angular

16.2.15 (2024-08-29)

@angular-devkit/build-angular

18.2.1 (2024-08-21)

@angular/cli

@angular-devkit/schematics-cli

@angular-devkit/build-angular

@angular/build

18.2.0 (2024-08-14)

@schematics/angular

@angular/build

18.1.4 (2024-08-07)

@angular/build

18.1.3 (2024-07-31)

@angular/build

18.1.2 (2024-07-24)

@angular/build

18.1.1 (2024-07-17)

@angular-devkit/build-angular

@angular/build

18.1.0 (2024-07-10)

@angular/cli

@schematics/angular

@angular/build

18.0.7 (2024-07-03)

@angular/cli

@angular-devkit/build-angular

@angular/build

18.0.6 (2024-06-26)

@angular/build

18.0.5 (2024-06-20)

@schematics/angular

@angular-devkit/build-angular

@angular/build

18.0.4 (2024-06-13)

@angular/build

18.0.3 (2024-06-05)

@angular/cli

@angular/build

18.0.2 (2024-05-29)

@schematics/angular

@angular/build

@angular/pwa

18.0.1 (2024-05-23)

@schematics/angular

@angular/build

18.0.0 (2024-05-22)

Breaking Changes

@angular/cli

• The ng doc command has been removed without a replacement. To perform searches, please visit www.angular.dev
• Node.js support for versions <18.19.1 and <20.11.1 has been removed.

@angular-devkit/build-angular

• By default, the index.html file is no longer emitted in the browser directory when using the application builder with SSR. Instead, an index.csr.html file is emitted. This change is implemented because in many cases server and cloud providers incorrectly treat the index.html file as a statically generated page. If you still require the old behavior, you can use the index option to specify the output file name.

  "architect": {
    "build": {
      "builder": "@angular-devkit/build-angular:application",
      "options": {
        "outputPath": "dist/my-app",
        "index": {
          "input": "src/index.html",
          "output": "index.html"
        }
      }
    }
  }

• The support for the legacy Sass build pipeline, previously accessible via NG_BUILD_LEGACY_SASS when utilizing webpack-based builders, has been removed.

Deprecations

@angular-devkit/schematics

• NodePackageLinkTask in @angular-devkit/schematics. A custom task should be created instead.

@angular/cli

@schematics/angular

@angular-devkit/architect

@angular-devkit/build-angular

@angular-devkit/schematics

@angular/build

17.3.8 (2024-05-22)

@angular/cli

@angular-devkit/schematics

17.3.7 (2024-05-08)

@angular-devkit/build-angular

@angular-devkit/schematics

17.3.6 (2024-04-25)

@angular-devkit/build-angular

17.3.5 (2024-04-17)

@angular-devkit/build-angular

17.3.4 (2024-04-11)

@angular-devkit/build-angular

16.2.14 (2024-04-11)

@angular-devkit/build-angular

17.3.3 (2024-04-02)

@schematics/angular

17.3.2 (2024-03-25)

@schematics/angular

@angular-devkit/build-angular

16.2.13 (2024-03-25)

@angular-devkit/build-angular

15.2.11 (2024-03-25)

@angular-devkit/build-angular

17.3.1 (2024-03-20)

@schematics/angular

@angular-devkit/build-angular

17.3.0 (2024-03-13)

@schematics/angular

@angular-devkit/build-angular

17.2.3 (2024-03-06)

@angular-devkit/build-angular

17.2.2 (2024-02-28)

@angular-devkit/build-angular

17.2.1 (2024-02-22)

@angular-devkit/build-angular

17.2.0 (2024-02-14)

@angular/cli

@schematics/angular

@angular-devkit/build-angular

@angular-devkit/schematics

@angular/create

17.1.4 (2024-02-14)

@angular/cli

@angular-devkit/build-angular

17.1.3 (2024-02-08)

@angular-devkit/build-angular

17.1.2 (2024-01-31)

@angular-devkit/build-angular

17.1.1 (2024-01-24)

@angular/cli

@schematics/angular

@angular-devkit/build-angular

@angular/ssr

16.2.12 (2024-01-24)

@angular-devkit/build-angular

17.1.0 (2024-01-17)

@schematics/angular

@angular-devkit/build-angular

17.0.10 (2024-01-10)

@angular/cli

@schematics/angular

@angular-devkit/core

17.0.9 (2024-01-03)

@angular/cli

@angular-devkit/schematics

17.0.8 (2023-12-21)

@angular/cli

@schematics/angular

@angular-devkit/build-angular

16.2.11 (2023-12-21)

@angular-devkit/build-angular

17.0.7 (2023-12-13)

@angular-devkit/build-angular

17.0.6 (2023-12-06)

@schematics/angular

@angular-devkit/build-angular

17.0.5 (2023-11-29)

Rolling back bbbe13d67 which appears to break file watching on Mac devices.

17.0.4 (2023-11-29)

@schematics/angular

@angular-devkit/build-angular

17.0.3 (2023-11-21)

@angular-devkit/build-angular

17.0.2 (2023-11-20)

@angular-devkit/build-angular

17.0.1 (2023-11-15)

@angular/cli

@schematics/angular

@angular-devkit/build-angular

17.0.0 (2023-11-08)

Breaking Changes

@schematics/angular

• Routing is enabled by default for new applications when using ng generate application and ng new. The --no-routing command line option can be used to disable this behaviour.
• ng g interceptor now generate a functional interceptor by default. or guard by default. To generate a class-based interceptor the --no-functional command flag should be used.
• rootModuleClassName, rootModuleFileName and main options have been removed from the public pwa and app-shell schematics.
• App-shell and Universal schematics deprecated unused appId option has been removed.

@angular-devkit/build-angular

• Node.js v16 support has been removed

  Node.js v16 is planned to be End-of-Life on 2023-09-11. Angular will stop supporting Node.js v16 in Angular v17. For Node.js release schedule details, please see: https://github.com/nodejs/release#release-schedule

@angular-devkit/schematics

• deprecated runExternalSchematicAsync and runSchematicAsync methods have been removed in favor of runExternalSchematic and runSchematic.

Deprecations

@angular-devkit/build-angular

• The browserTarget in the dev-server and extract-i18n builders have been deprecated in favor of buildTarget.

@angular/cli

@schematics/angular

@angular-devkit/build-angular

@angular-devkit/schematics

@angular/pwa

@angular/ssr

@ngtools/webpack

16.2.10 (2023-11-08)

@angular-devkit/build-angular

16.2.8 (2023-10-25)

@angular/cli

16.2.7 (2023-10-19)

@schematics/angular

16.2.6 (2023-10-11)

@angular-devkit/build-angular

15.2.10 (2023-10-05)

@angular-devkit/build-angular

14.2.13 (2023-10-05)

@angular-devkit/build-angular

16.2.5 (2023-10-04)

@angular-devkit/build-angular

16.2.4 (2023-09-27)

@schematics/angular

16.2.3 (2023-09-20)

@angular-devkit/build-angular

@ngtools/webpack

16.2.2 (2023-09-13)

@angular-devkit/build-angular

16.2.1 (2023-08-30)

@angular-devkit/build-angular

16.2.0 (2023-08-09)

@angular-devkit/build-angular

16.1.8 (2023-08-04)

16.1.7 (2023-08-02)

@angular-devkit/build-angular

16.1.6 (2023-07-26)

@angular-devkit/build-angular

16.1.5 (2023-07-20)

@angular/cli

@angular-devkit/build-angular

16.1.4 (2023-07-06)

@angular-devkit/build-angular

16.1.3 (2023-06-29)

@angular-devkit/build-angular

15.2.9 (2023-06-28)

@angular/cli

16.1.2 (2023-06-28)

@angular/cli

@angular-devkit/build-angular

14.2.12 (2023-06-28)

@angular/cli

16.1.1 (2023-06-22)

@angular-devkit/build-angular

16.1.0 (2023-06-13)

@schematics/angular

@angular-devkit/build-angular

16.0.6 (2023-06-13)

@angular-devkit/build-angular

16.0.5 (2023-06-07)

@angular-devkit/build-angular

16.0.4 (2023-06-01)

@angular-devkit/build-angular

16.0.3 (2023-05-25)

@angular-devkit/build-angular

16.0.2 (2023-05-17)

@angular-devkit/build-angular

16.0.1 (2023-05-10)

@angular-devkit/build-angular

@angular-devkit/schematics

@angular/pwa

16.0.0 (2023-05-03)

Breaking Changes

@angular/cli

• The deprecated defaultCollection workspace option has been removed. Use schematicCollections instead.

  Before

  "defaultCollection": "@angular/material"

  After

  "schematicCollections": ["@angular/material"]

• The deprecated defaultProject workspace option has been removed. The project to use will be determined from the current working directory.

• Node.js v14 support has been removed

  Node.js v14 is planned to be End-of-Life on 2023-04-30. Angular will stop supporting Node.js v14 in Angular v16. Angular v16 will continue to officially support Node.js versions v16 and v18.

@schematics/angular

• ng g resolver and ng g guard now generate a functional resolver or guard by default. It is still possible to generate a (deprecated) class-based resolver or guard by using ng g resolver --no-functional or ng g guard --no-functional.
• The CLI no longer allows to generate CanLoad guards. Use CanMatch instead.

#

• • TypeScript 4.8 is no longer supported.

@angular-devkit/build-angular

• Deprecated outputPath and outputPaths from the server and browser builder have been removed from the builder output. Use outputs instead.

  Note: this change does not effect application developers.

@angular-devkit/core

• Several changes to the SchemaRegistry.
  • compile method now returns a Promise.
  • Deprecated flatten has been removed without replacement.
• • ContentHasMutatedException, InvalidUpdateRecordException, UnimplementedException and MergeConflictException API from @angular-devkit/core have been removed in favor of the API from @angular-devkit/schematics.
  • UnsupportedPlatformException - A custom error exception should be created instead.

@angular-devkit/schematics

• The depracated UpdateBuffer has been removed and UpdateBuffer2 is renamed to UpdateBuffer. With this change the related and deprecated symbols ContentCannotBeRemovedException and Chunk have also been removed.

@ngtools/webpack

• NGCC integration has been removed and as a result Angular View Engine libraries will no longer work.

@schematics/angular

@angular/cli

#

@angular-devkit/architect

@angular-devkit/build-angular

@angular-devkit/core

@angular-devkit/schematics

@ngtools/webpack

15.2.8 (2023-05-03)

@angular/cli

15.2.7 (2023-04-26)

@angular/cli

@schematics/angular

15.2.6 (2023-04-12)

@schematics/angular

15.2.5 (2023-04-05)

@angular/cli

Special Thanks

Alan Agius

15.2.4 (2023-03-16)

@angular-devkit/build-angular

Special Thanks

Alan Agius

14.2.11 (2023-03-16)

@angular-devkit/build-angular

Special Thanks

Alan Agius and Joey Perrott

13.3.11 (2023-03-16)

@angular-devkit/build-angular

Special Thanks

Alan Agius and Joey Perrott

15.2.3 (2023-03-15)

@angular-devkit/build-angular

Special Thanks

Alan Agius and Paul Gschwendtner

15.2.2 (2023-03-08)

@angular-devkit/schematics-cli

@angular-devkit/build-angular

Special Thanks

Alan Agius

15.2.1 (2023-03-01)

@angular-devkit/build-angular

Special Thanks

Alan Agius and Paul Gschwendtner

15.2.0 (2023-02-22)

@angular/cli

@angular-devkit/schematics-cli

@angular-devkit/build-angular

Special Thanks

Alan Agius, Charles Lyding, Doug Parker, Jason Bedard, Joey Perrott, Marvin and Paul Gschwendtner

15.1.6 (2023-02-15)

@angular/cli

@angular-devkit/build-angular

Special Thanks

Alan Agius and Charles Lyding

15.1.5 (2023-02-08)

@angular/cli

@schematics/angular

@angular-devkit/build-angular

Special Thanks

Alan Agius, Charles Lyding, Kristiyan Kostadinov and Ricardo

15.1.4 (2023-02-01)

@angular-devkit/build-angular

Special Thanks

Alan Agius

15.1.3 (2023-01-25)

@angular/cli

@schematics/angular

@angular-devkit/build-angular

@angular-devkit/core

Special Thanks

Alan Agius, Charles Lyding and Doug Parker

15.1.2 (2023-01-18)

@angular/cli

@schematics/angular

@angular-devkit/build-angular

Special Thanks

Alan Agius, Charles Lyding and Doug Parker

15.1.1 (2023-01-12)

@angular-devkit/build-angular

Special Thanks

Alan Agius

15.1.0 (2023-01-11)

Deprecations

@angular-devkit/schematics

• The Observable based SchematicTestRunner.runSchematicAsync and SchematicTestRunner.runExternalSchematicAsync method have been deprecated in favor of the Promise based SchematicTestRunner.runSchematic and SchematicTestRunner.runExternalSchematic.

@schematics/angular

@angular-devkit/build-angular

@angular-devkit/schematics

Special Thanks

Alan Agius, Andrew Scott, Charles Lyding, Cédric Exbrayat, Doug Parker, Felix Hamann, Jason Bedard, Joey Perrott and Kristiyan Kostadinov

15.0.5 (2023-01-06)

@angular-devkit/build-angular

Special Thanks

Alan Agius, Kristiyan Kostadinov, Paul Gschwendtner and aanchal

15.0.4 (2022-12-14)

@angular-devkit/build-angular

Special Thanks

Alan Agius and Charles Lyding

15.0.3 (2022-12-07)

@angular-devkit/build-angular

Special Thanks

Charles Lyding, Dominic Elm and Paul Gschwendtner

15.0.2 (2022-11-30)

@angular-devkit/build-angular

@ngtools/webpack

Special Thanks

Alan Agius and Juuso Valkeejärvi

15.0.1 (2022-11-23)

@angular/cli

@schematics/angular

@angular-devkit/build-angular

Special Thanks

Alan Agius, Charles Lyding, Doug Parker, Joey Perrott and Piotr Wysocki

15.0.0 (2022-11-16)

Breaking Changes

@angular/cli

• The Angular CLI no longer supports 16.10.x, 16.11.x and 16.12.x. Current minimum versions of Node.js are 14.20.0, 16.13.0 and 18.10.0.
• Node.js versions older than 14.20 are no longer supported.
• The 'path' option in schematics schema no longer has a special meaning. Use 'workingDirectory' smart default provider should be used instead.

@schematics/angular

• Removed unused appDir option from Universal and App-Shell schematic. This option can safely be removed if present since it no longer has effect.

#

• analyticsSharing option in the global angular configuration has been removed without replacement. This option was used to configure the Angular CLI to access to your own users' CLI usage data.

  If this option is used, it can be removed using ng config --global cli.analyticsSharing undefined.

• analytics APIs have been removed without replacement from @angular-devkit/core and @angular-devkit/architect.

@angular-devkit/build-angular

• TypeScript versions older than 4.8.2 are no longer supported.

• The server builder bundleDependencies option has been removed. This option was used pre Ivy. Currently, using this option is unlikely to produce working server bundles.

  The externalDependencies option can be used instead to exclude specific node_module packages from the final bundle.

• • Deprecated support for tilde import has been removed. Please update the imports by removing the ~.

  Before

  @import '~font-awesome/scss/font-awesome';

  After

  @import 'font-awesome/scss/font-awesome';

  • By default the CLI will use Sass modern API, While not recommended, users can still opt to use legacy API by setting NG_BUILD_LEGACY_SASS=1.

• Internally the Angular CLI now always set the TypeScript target to ES2022 and useDefineForClassFields to false unless the target is set to ES2022 or later in the TypeScript configuration. To control ECMA version and features use the Browerslist configuration.

• require.context are no longer parsed. Webpack specific features are not supported nor guaranteed to work in the future.
• Producing ES5 output is no longer possible. This was needed for Internet Explorer which is no longer supported. All browsers that Angular supports work with ES2015+
• server builder bundleDependencies option now only accept a boolean value.
• Deprecated support for Stylus has been removed. The Stylus package has never reached a stable version and its usage in the Angular CLI is minimal. It's recommended to migrate to another CSS preprocessor that the Angular CLI supports.

@angular-devkit/core

• Workspace projects with missing root is now an error.

@ngtools/webpack

• TypeScript versions older than 4.8.2 are no longer supported.

@schematics/angular

@angular/cli

#

@angular-devkit/build-angular