schematics API reference

[xxyyzz2050]

I see that there is a guide for Schematics, but I don't see any reference for Schematics API, so we can learn all about all Schematics functions.

[KingDarBoja]

Was looking for the same stuff on the official documentation, hopefully the Angular team will provide it soon (I hope). +1

[xxyyzz2050]

any news?

@alan-agius4

[alan-agius4]

There is no ETA for this yet.

[KingDarBoja]

Is there anything that can be done by the community to improve the docs? There are few tutorials with some API functions explained (like this one) so maybe extracting the description and using the type definitions would help with this task.

[d-koppenhagen]

Hey, I am planning to write a blog post about some very common API Util functions you can use. Unfortunately those utils aren't documented yet but can basically be found here: https://github.com/angular/angular-cli/tree/master/packages/schematics/angular/utility

You can import the function from @schematics/angular/utility/file.

So for example handling changes on package.json will work like this:

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics/';
import {
  NodeDependency,
  NodeDependencyType
  getPackageJsonDependency,
  addPackageJsonDependency,
  removePackageJsonDependency,
} from '@schematics/angular/utility/dependencies';

export function playground(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const dep: NodeDependency = {
      type: NodeDependencyType.Dev,
      name: 'my-package',
      version: '~0.3.4-beta.1',
      overwrite: true,
    };

    addPackageJsonDependency(tree, dep);
    console.log(getPackageJsonDependency(tree, 'my-package'))
    // { type: 'dependencies', name: 'typescript', version: '~3.9.2' }

    removePackageJsonDependency(tree, 'my-package');
    console.log(getPackageJsonDependency(tree, 'my-package'))
    // null

    return tree;
  };
}

I think it would be really helpful I the docs for the utils will be generated directly from the source in the future.
Probably a separate docs site would be great such as schematics.angular.io or something similar

[alan-agius4]

@d-koppenhagen, those utils are not considered as part of the public API and might break without warning in any release.

There are plans to provide some utilities via public API but this is still in planning stages.

[d-koppenhagen]

Okay that's good to know. Yes it would be really great as I've seen a lots of people authoring schematics with almost the same util functions which is I think not the best.

[d-koppenhagen]

@alan-agius4 is there a way I / others can help bringing this to a next level? I would really like to help and contribute but don't know where to start.

[alan-agius4]

Hi @d-koppenhagen, thanks for your interest in helping with this.I do think however that this needs to be taken by someone on the team. The reason being is that entire API surface needs to be reviewed and decide which parts of it should be kept, modified or deprecated.