Angular Schematics: How to define default variables in schema.json? (projectName)

Question

How to define default variables for angular schematics "properties" in schema.json?

I have tried to look into the angular source code itself but I couldn't figure it out. I have found out that if the keyword "$source" is being used, somehow the string in front of it will be resolved to some value.

For example "argv" and "projectName" are two variables that they will be resolved to actual values when they are written like this:

     "project": {
         "alias": "p",
         "type": "string",
         "description": "The name of the project.",
         "$default": {
             "$source": "projectName"
         }
     },

or

    "name": {
      "type": "string",
      "description": "The package name for the new schematic.",
      "$default": {
        "$source": "argv",
        "index": 0
      }
    },

So how can I define my own variable? Are they actually variables? What other variables are available?

I also found another example which is not working if I copy-paste it into my own project:

    "version": {
      "type": "string",
      "description": "The version of the Angular CLI to use.",
      "visible": false,
      "$default": {
        "$source": "ng-cli-version"
      }
    },

Here find the full code

From my observation, I expect this to be resolved to a value, but I get undefiend.

Thank you folks in advance!

Answer 1

The variables you define will certainly depend on the behavior for your schematic. For example, I have a new application schematic with a custom variable to allow users to specify the type of authentication to scaffold into the application:

To invoke this schematic from the command-line, the user would input ng new my-application-schematic-with-sso --collection=@simple-schematic --authentication=SSO (the x-prompt provides a list of options to the user if the command line switch is not explicitly provided. See also Angular ng-new schema for style options.

"authentication": {
    "description": "The authentication strategy to use",
    "default": "None",
    "x-prompt": {
        "message": "Which authentication strategy would you like to use?",
        "type": "list",
        "items": [
            {
                "value": "None",
                "label": "None"
            },
            {
                "value": "SSO",
                "label": "SSO"
            }
        ]
    }
},

This schematic also makes use of the argv pattern to capture the name of the workspace:

"name": {
    "description": "The name of the workspace",
    "type": "string",
    "$default": {
        "$source": "argv",
        "index": 0
    }
},...

So the command line syntax to invoke this schematic would look something like ng new my-new-schematic --collection=@simple-schematic and would generate a new workspace titled my-new-schematic. Since the --authentication flag is not provided, the user would be prompted to select either None or SSO.

One important behavior related to the schema and variables you define that can lead to the undefined issue (esp. when your variable has a default value) you noted in your original question is not correctly linking the schema to the schematic command.

For example, the schema property of the ng-new schematic object, indicates how to translate the provided CLI inputs into the corresponding object passed to your custom schematic.

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "extends": "@schematics/angular",
  "schematics": {
    "ng-new": {
      "description": "new workspace",
      "factory": "./ng-new",
      "schema": "./ng-new/schema.json"
    }
  }
}

Two different screenshots from debugging the tests depending on whether the schema property is specified or not:

And again with the schema explicitly specified:

Answer 2

Just use "default": "YOUR_VALUE" but don't forget to run npm run build after.

Answer 3

OffTopic: There is also interpolation .
You can find it in packages/_/devkit/package/schema.json. ;-)

You may have a look in
packages/angular_devkit/core/src/json/schema/registry.ts
where you can find a method called
addSmartDefaultProvider<T>(source: string, provider: SmartDefaultProvider<T>)

It looks like they are using this method to create such "smart defaults" as how they call it, but not always.
The check for argv in packages/angular/cli/utilities/json-schema.ts is done via
const $defaultIndex = (json.isJsonObject($default) && $default['$source'] == 'argv')
So no unified approach. Quite hacky imho.

Within the addSmartDefaultProvider method body you will find the following funny block:

// We cheat, heavily.
compilationSchemInfo.smartDefaultRecord.set(
// tslint:disable-next-line:no-any
   JSON.stringify((it as any).dataPathArr.slice(1, (it as any).dataLevel + 1) as string[]),
   schema,
);

If you are going to step further, you will discover:

• Angular-CLI makes use of the Ajv library.
• The parameter it represents the current 'Schema Compilation Context'
• dataPathArr property is a 'Vaidation time variable'
  ....

Answer 4

DevRok was almost there. I think to fully answer you question we need to look at usage of addSmartDefaultProvider. I found these references in the 7.3.x branch (because that's what we are still using at work).

Reference 1 in packages/angular/cli/models/schematic-command.ts

workflow.registry.addSmartDefaultProvider('projectName', () => {

Reference 2 in packages/angular/cli/commands/new-impl.ts

this._workflow.registry.addSmartDefaultProvider('ng-cli-version', () => version);

So it seems ng-cli-version would only work when running ng new, not ng generate. It also seems that ng-cli-version and projectName are the only defined smart default providers for now, but it should be fairly straight forward to add more in the future.

For completion sake, I'd like to reference DevRok's answer for the pseudo smart default provider of argv being defined in packages/angular/cli/utilities/json-schema.ts.

Answer 5

Not sure how you set it in the schema.json... Not sure if there is a key value pair for it ("default":"value" didn't do anything).

So I worked around with an if statement in the factory function (index.ts)

if (!_options.yourVariable) {
     _options.yourVariable = 'yourDefaultValue'
}

Works well enough.