Add per-template CLI parameter definitions to manifest

[nick-pape]

Summary

The dev design says the template manifest should include "CLI Parameters (defined with ts-command-line JSON syntax), enforced after calling the template." This would allow individual templates to declare their own custom required/optional parameters beyond the base set provided by the CLI.

Requirements

Schema addition

Add a parameters field to template.json that declares additional CLI flags using ts-command-line JSON definitions:

{
  "name": "webpart-react",
  "version": "1.0.0",
  "spfxVersion": "1.22.2",
  "parameters": [
    {
      "parameterName": "--use-fluent-ui",
      "parameterType": "flag",
      "description": "Include Fluent UI React dependencies"
    },
    {
      "parameterName": "--react-version",
      "parameterType": "choice",
      "description": "React version to use",
      "alternatives": ["17", "18"],
      "defaultValue": "18"
    }
  ]
}

Behavior

• Template-specific parameters are dynamically added to the create command when a template is selected
• Parameters are validated after template selection
• Parameter values are merged into the template context and available in EJS templates
• In interactive mode, template-specific parameters are prompted for after template selection
• Unknown parameters for a given template produce a clear error

Design considerations

• This requires a two-pass approach: first parse --template to load the manifest, then dynamically add template-specific flags
• @rushstack/ts-command-line may need dynamic parameter registration or a two-phase parse
• Consider whether contextSchema (existing) and parameters (new) should be unified or kept separate
  • contextSchema = what the template expects in its rendering context
  • parameters = what the CLI should collect from the user
  • These are related but not identical (CLI may compute context variables from parameters)

Implementation notes

• Extend ISPFxTemplateJson with optional parameters array
• Define parameter types matching ts-command-line: flag, string, choice, stringList, choiceList, integer
• Parse --template first, fetch the template manifest, then validate remaining flags against the manifest's parameter definitions
• Merge parameter values into the render context

Acceptance criteria

• Templates can declare custom parameters in template.json
• Custom parameters are validated by the CLI
• Custom parameter values are available in EJS template context
• Interactive mode prompts for template-specific parameters
• Clear error messages for missing required template parameters

[nick-pape]

Investigation: ts-command-line support for dynamic parameters

Investigated whether @rushstack/ts-command-line supports the two-phase parsing needed for this feature (parse --template first, then dynamically register template-specific parameters).

Findings

ScopedCommandLineAction supports this pattern, but with a constraint:

• Phase 1: Define --template as a scoping parameter in onDefineParameters()
• Phase 2: Library calls onDefineScopedParameters() after phase 1 parsing — at this point --template is resolved, so the manifest can be loaded and template-specific parameters registered dynamically
• Constraint: Requires a -- separator between base args and template-specific args:

  spfx create --template webpart-react -- --use-fluent-ui --react-version 18
  

Other approaches for flat syntax (no --) all have significant trade-offs:

• Manual process.argv pre-scan: Fragile, parses --template outside the framework
• Register all params from all templates: Noisy help text, can't enforce per-template required
• Custom remainder parsing: Still needs --, loses help text/validation

Decision

Punting to GA (1.0.0). The feature is feasible via ScopedCommandLineAction but the UX and design trade-offs (the -- separator, interactive mode prompting, relationship with contextSchema) warrant more thought. Not blocking Public Preview.