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.

[angular-robot]

Just a heads up that we kicked off a community voting process for your feature request. There are 20 days until the voting process ends.

Find more details about Angular's feature request process in our documentation.

[dgp1130]

Agreed that schematics documentation is quite lacking right now and we are hoping to improve it. We have a near-future project adding common utilities to schematics and this would be a good opportunity to refactor the documentation and provide more comprehensive information. There will also be some non-trivial infrastructure requirements to generate API documentation from JSDoc comments and plumb them through to angular.io. This is already done for other Angular APIs, but it is more complicated for the CLI since we live in a different GitHub repository than angular.io.

This work is being tracked separately, so I don't think there's anything immediately actionable in this issue. I'm going to close it for the time being, but we hoping to improve this area in the near-future.

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}