SharePoint / SharePoint/spfx

Add per-template CLI parameter definitions to manifest

Open
#98 1 comment 0 reactions 1 assignee View on GitHub

@nick-pape is already working on this.

Since Mar 5, 2026.

area: api type: enhancement
Dominant language
TypeScript
Stars
32
Forks
18
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.