Schematics documentation

[bmayen]

Bug Report or Feature Request (mark with an x)

- [ ] bug report -> please search issues before submitting
- [x] feature request

Versions.

Latest

Desired functionality.

Very excited to see Schematics support has landed! Will usage be documented here or is this something we should look for over at angular/devkit repo?

One thing we would love to be able to do is create our own application structure. Also, additional generators for things like lazy-loaded-feature which contain ngModule, component ts, html, scss, etc. Are these supported use-cases?

I have no idea about what is chematics, but as it is now a way to generate app, I'd really like to see full docs. I wonder how you guys found possible to release it without any docs. VERY frustrating.

[bmayen]

@AloeDream, this issue is trying to clarify, first and foremost, whether this repo is even the right place for this documentation. Technically, the functionality is provided via https://github.com/angular/devkit. Ideally, documentation is also provided from that repo and maybe we get some recipes here https://github.com/angular/angular-cli/wiki/stories.

But, yes, would be great to get some feedback from the team with a rough estimate on when we might expect that. My guess is that this functionality was added primarily for internal purposes and the fact that it enables users to customize is icing on the cake. In which case, documentation probably isn't the highest priority at the moment.

In the meantime, you might want to consider opening a similar issue over at angular/devkit repo.

@bmayen this feature is critical for CLI, as I go type ng help to review ng new command parameters and see that many of them disappeared and one new appeared without any explanation how to use it. So yes, I think this is the right place to at least mention where to find its docs and how it's not the highest priority, as I can't create new or update existing project without those docs?

[Splaktar]

There should be some slides and talks coming out of AngularMix in a couple weeks which provide considerable information about Schematics. I'm unsure if there are plans to provide significant documentation on the feature before then, but hopefully soon :)

Some details can be found in this blog post.

[tomwanzek]

@Brocco First of all, thanks for all the hard work on the CLI 🥇Love it.

I have one quick question related to @Splaktar 's above comment. AFAIK you presented at AngularMix on the CLI/schematics, but the session was not recorded/published on the youtube channel. Is there any material (slides etc) you could make available? Thanks in advance.

[Splaktar]

I don't believe that there were many slides in that talk. Most of it was a demo of how the schematics work. It's very unfortunate that it wasn't recorded :(

I know that there is work happening to document the schematics feature. However I have no idea what the ETA might be.

[Splaktar]

@tomwanzek schematics were on the latest Angular Air and they walk through the whole process. Thanks @Brocco! I was able to get everything working after watching the show.

[tomwanzek]

@Splaktar Thanks for the hint re ngAir...checking it out.

[jimdubbs]

@Splaktar were you able to test our your custom schematics? Following @Brocco 's instructions on the ngAir episode I ran the following commands:
npm i -g @angular-devkit/schematics
npm i @schematics.schematics -g
schematics @schematics/schematics:schematic --name schematics-test

i than installed/built schematics-test, and npm link'd it.
In an empty directory I attempt to run: schematics schematics-test:my-full-schematic --name test
and I get the error "tree.branch is not a function". I've spent a few hours trying to figure out what this could possibly be with no luck. Any insight?

[Splaktar]

@jimdubbs Yes, I got everything working.

I also ran into those tree.branch is not a function errors. I think that I hit them when trying to generate an application using my schematics with ng new. I've since switched to just using the schematics command directly and I haven't hit that issue since. It's most likely just a configuration issue.

Note that my solution combined the contents of @schematics/angular with the output of @schematics/schematics. I don't think that the output of @schematics/schematics is really ready for prime time yet, but it gave me enough to work with that I could wire everything up. Specifically, I have utility/ and strings.ts in my-schematics/src/.

I also had to add the following to the package.json generated by @schematics/schematics to get npm test to work:

  "devDependencies": {
    ...
    "common-tags": "1.4.0",
    "portfinder": "1.0.13",
    "selenium-mock": "0.1.5",
    ...
}

Here's my full package.json, not all of this is required (like angular here just helps my IDE)

{
  "name": "my-schematics",
  "version": "0.0.1",
  "private": true,
  "description": "Schematic plugins to Angular Devkit",
  "engines": {
    "node": ">= 6.11.0",
    "npm": ">= 3.10.0"
  },
  "keywords": [
    "schematics"
  ],
  "dependencies": {
    "@angular-devkit/core": "0.0.20",
    "@angular-devkit/schematics": "0.0.34",
    "@types/jasmine": "2.6.2",
    "@types/node": "8.0.47",
    "jasmine": "2.8.0",
    "typescript": "2.5.3"
  },
  "devDependencies": {
    "@angular/common": "4.4.6",
    "@angular/compiler": "4.4.6",
    "@angular/core": "4.4.6",
    "@angular/platform-browser": "4.4.6",
    "@angular/platform-browser-dynamic": "4.4.6",
    "@angular/router": "4.4.6",
    "@types/jasmine": "2.6.2",
    "@types/jasminewd2": "2.0.3",
    "@types/node": "6.0.60",
    "common-tags": "1.4.0",
    "portfinder": "1.0.13",
    "protractor": "5.2.0",
    "selenium-mock": "0.1.5",
    "ts-node": "3.3.0",
    "tslint": "5.8.0",
    "zone.js": "0.8.18"
  },
  "optionalDependencies": {},
  "peerDependencies": {},
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "schematics": "schematics",
    "list": "npm run schematics -- my-schematics --list-schematics",
    "test": "npm run build && jasmine src/**/*_spec.js"
  },
  "schematics": "./src/collection.json"
}

[Splaktar]

@jimdubbs I actually just hit that error again while trying to run my schematics globally in a brand new Node environment.

I resolved it by moving "@angular-devkit/schematics": "0.0.34" from dependencies to devDependencies, and peerDependencies in my-schematics repo.

Then I ran into Cannot find module 'rxjs/add/operator/map'. This was fixed by adding "rxjs": "5.4.2", to the dependencies of my-schematics repo.

[jimdubbs]

@Splaktar Still running into the tree.branch is not a function issue. My package.json dependencies for my schematic project is
"dependencies": { "@angular-devkit/core": "0.0.20", "@types/jasmine": "2.6.2", "@types/node": "8.0.47", "jasmine": "2.8.0", "typescript": "2.5.3" }, "peerDependencies": { "@angular-devkit/schematics": "0.0.34" }, "devDependencies": { "@angular-devkit/schematics": "0.0.34", "@angular/common": "4.4.6", "@angular/compiler": "4.4.6", "@angular/core": "4.4.6", "@angular/platform-browser": "4.4.6", "@angular/platform-browser-dynamic": "4.4.6", "@angular/router": "4.4.6", "@types/jasmine": "2.6.2", "@types/jasminewd2": "2.0.3", "@types/node": "6.0.60", "common-tags": "1.4.0", "portfinder": "1.0.13", "protractor": "5.2.0", "selenium-mock": "0.1.5", "ts-node": "3.3.0", "tslint": "5.8.0", "zone.js": "0.8.18", "rxjs": "5.4.2" }

Globally I have the following installed:
angular-devkit/core@0.0.20
angular-devkit/schematics@0.0.34
angular/cli@1.5.0-rc.5
schematics/schematics@0.0.3

I've npm linked my schematics project so I should be able to access it globally.

from the command line I attempt to run "schematics schematics-test:my-full-schematic --name test" from an empty folder and I get the tree.branch error. Any insight as to what Im doing wrong?do I need to have something installed locally in the directory im trying to run the schematics command from?