feat: add usage examples to CLI help output#262
Open
vystartasv wants to merge 8 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an examples framework to the SPFx CLI help output by extending the shared action base, and provides initial examples for spfx create. The PR also includes additional behavior/documentation changes to list-templates and create parameter requirements that go beyond the stated PR scope.
Changes:
- Add
getExamples()+renderHelpText()override inSPFxActionBaseto append anEXAMPLESsection to action help output. - Add
CreateActionexamples and make--library-nameoptional (with a default). - Update
ListTemplatesActionhelp text and add--spfx-versionfiltering behavior.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| apps/spfx-cli/src/cli/actions/SPFxActionBase.ts | Adds the base help-text rendering extension point for appending formatted usage examples. |
| apps/spfx-cli/src/cli/actions/CreateAction.ts | Makes --library-name optional, defaults it during context generation, and supplies initial usage examples. |
| apps/spfx-cli/src/cli/actions/ListTemplatesAction.ts | Updates command documentation and filters displayed templates by --spfx-version. |
Comments suppressed due to low confidence (1)
apps/spfx-cli/src/cli/actions/CreateAction.ts:212
buildBuiltInContext()requireslibraryName: string, butthis._libraryNameParameter.value || rawSolutionNamecan evaluate toundefinedwhen the user omits both--library-nameand--solution-name. This will either fail type-checking or produce runtime issues in template rendering. Since the parameter description says it defaults to the solution name, use the already-computedsolutionName(always defined) and trim the CLI value.
const builtInContext: ISPFxBuiltInContext = buildBuiltInContext(
{
componentName,
libraryName: this._libraryNameParameter.value || rawSolutionName,
spfxVersion: template.spfxVersion,
solutionName: rawSolutionName || undefined,
componentAlias: this._componentAliasParameter.value?.trim() || undefined,
componentDescription: this._componentDescriptionParameter.value?.trim() || undefined
},
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+183
to
+200
| public renderHelpText(): string { | ||
| const base: string = super.renderHelpText(); | ||
| const examples: string[] = this.getExamples(); | ||
| if (examples.length === 0) { | ||
| return base; | ||
| } | ||
|
|
||
| // Append examples after the last line of base help | ||
| const lines: string[] = base.split('\n'); | ||
| lines.push(''); | ||
| lines.push('EXAMPLES'); | ||
| for (const example of examples) { | ||
| lines.push(''); | ||
| lines.push(` ${example}`); | ||
| } | ||
| lines.push(''); | ||
| return lines.join('\n'); | ||
| } |
Comment on lines
+41
to
+46
| // Apply --spfx-version filter if provided (user expects filter, not just branch selection) | ||
| const spfxVersion: string | undefined = this._spfxVersionParameter.value?.trim(); | ||
| if (spfxVersion) { | ||
| const filteredTemplates = [...templates.values()].filter( | ||
| (t) => t.spfxVersion && t.spfxVersion.startsWith(spfxVersion) | ||
| ); |
Comment on lines
+273
to
+280
| protected getExamples(): string[] { | ||
| return [ | ||
| 'Scaffold a new React web part in the current directory:\n spfx create --template webpart-react --component-name "HelloWorld" --library-name "helloworld-library" --solution-name "helloworld" --component-description "A Hello World web part"', | ||
| 'Scaffold an extension with pnpm (skipping npm install):\n spfx create --template extension-field --component-name "ColorField" --library-name "color-field-lib" --solution-name "color-field" --package-manager pnpm --skip-install', | ||
| 'Scaffold a web part without npm install, specifying a local template source:\n spfx create --template webpart-react --component-name "MyWebPart" --library-name "mywebpart" --solution-name "mywebpart" --skip-install --local-source ./my-templates', | ||
| 'Scaffold a web part using a specific SPFx version:\n spfx create --template webpart-react --component-name "MyWP" --component-description "Description" --spfx-version 1.22 --skip-install' | ||
| ]; | ||
| } |
Comment on lines
+39
to
+44
| const templates: SPFxTemplateCollection = await this._fetchTemplatesAsync(manager); | ||
|
|
||
| const formattedTable: string = await templates.toFormattedStringAsync(); | ||
| terminal.writeLine(formattedTable); | ||
| // Apply --spfx-version filter if provided (user expects filter, not just branch selection) | ||
| const spfxVersion: string | undefined = this._spfxVersionParameter.value?.trim(); | ||
| if (spfxVersion) { | ||
| const filteredTemplates = [...templates.values()].filter( |
Comment on lines
+190
to
+199
| // Append examples after the last line of base help | ||
| const lines: string[] = base.split('\n'); | ||
| lines.push(''); | ||
| lines.push('EXAMPLES'); | ||
| for (const example of examples) { | ||
| lines.push(''); | ||
| lines.push(` ${example}`); | ||
| } | ||
| lines.push(''); | ||
| return lines.join('\n'); |
| { | ||
| componentName, | ||
| libraryName: this._libraryNameParameter.value, | ||
| libraryName: this._libraryNameParameter.value || rawSolutionName, |
Comment on lines
+274
to
+280
| return [ | ||
| 'Scaffold a new React web part in the current directory:\n spfx create --template webpart-react --component-name "HelloWorld" --library-name "helloworld-library" --solution-name "helloworld" --component-description "A Hello World web part"', | ||
| 'Scaffold an extension with pnpm (skipping npm install):\n spfx create --template extension-field --component-name "ColorField" --package-manager pnpm', | ||
| 'Scaffold a web part without npm install, specifying a local template source:\n spfx create --template webpart-react --component-name "MyWebPart" --library-name "mywebpart" --solution-name "mywebpart" --local-source ./my-templates', | ||
| 'Scaffold a web part using a specific SPFx version:\n spfx create --template webpart-react --component-name "MyWP" --component-description "Description" --spfx-version 1.22' | ||
| ]; | ||
| } |
Comment on lines
+41
to
+42
| // Apply --spfx-version filter if provided (user expects filter, not just branch selection) | ||
| const spfxVersion: string | undefined = this._spfxVersionParameter.value?.trim(); |
Comment on lines
15
to
19
| documentation: | ||
| 'This command lists all available templates from the default GitHub source ' + | ||
| 'and any additional sources specified with --local-source or --remote-source.' | ||
| 'and any additional sources specified with --local-source or --remote-source. ' + | ||
| 'Use --spfx-version to filter templates by version (e.g., "--spfx-version 1.22").' | ||
| }, |
Comment on lines
83
to
88
| this._libraryNameParameter = this.defineStringParameter({ | ||
| parameterLongName: '--library-name', | ||
| argumentName: 'LIBRARY_NAME', | ||
| description: 'The library name for the component', | ||
| required: true | ||
| description: 'The library name for the component. Defaults to the solution name if not specified.', | ||
| required: false | ||
| }); |
Comment on lines
83
to
88
| this._libraryNameParameter = this.defineStringParameter({ | ||
| parameterLongName: '--library-name', | ||
| argumentName: 'LIBRARY_NAME', | ||
| description: 'The library name for the component', | ||
| required: true | ||
| description: 'The library name for the component. Defaults to the solution name if not specified.', | ||
| required: false | ||
| }); |
Comment on lines
+41
to
+54
| // Apply --spfx-version filter if provided (user expects filter, not just branch selection) | ||
| const spfxVersion: string | undefined = this._spfxVersionParameter.value?.trim(); | ||
| if (spfxVersion) { | ||
| const filteredTemplates = [...templates.values()].filter( | ||
| (t) => t.spfxVersion && t.spfxVersion.startsWith(spfxVersion) | ||
| ); | ||
| if (filteredTemplates.length === 0) { | ||
| terminal.writeLine( | ||
| `No templates found for SPFx version "${spfxVersion}". ` + | ||
| `Use "spfx list-templates" (without --spfx-version) to see all available versions.` | ||
| ); | ||
| return; | ||
| } | ||
| const displayCollection: SPFxTemplateCollection = new SPFxTemplateCollection(filteredTemplates); |
Comment on lines
15
to
19
| documentation: | ||
| 'This command lists all available templates from the default GitHub source ' + | ||
| 'and any additional sources specified with --local-source or --remote-source.' | ||
| 'and any additional sources specified with --local-source or --remote-source. ' + | ||
| 'Use --spfx-version to filter templates by version (e.g., "--spfx-version 1.22").' | ||
| }, |
| } | ||
|
|
||
| // Append examples after the last line of base help | ||
| const lines: string[] = base.replace(/\r$/, '').split('\n'); |
Comment on lines
206
to
210
| componentName, | ||
| libraryName: this._libraryNameParameter.value, | ||
| libraryName: this._libraryNameParameter.value || rawSolutionName, | ||
| spfxVersion: template.spfxVersion, | ||
| solutionName: rawSolutionName || undefined, | ||
| componentAlias: this._componentAliasParameter.value?.trim() || undefined, |
Comment on lines
+42
to
+46
| const spfxVersion: string | undefined = this._spfxVersionParameter.value?.trim(); | ||
| if (spfxVersion) { | ||
| const filteredTemplates = [...templates.values()].filter( | ||
| (t) => t.spfxVersion && t.spfxVersion.startsWith(spfxVersion) | ||
| ); |
Comment on lines
+14
to
+18
| summary: 'Lists available SPFx templates from configured sources', | ||
| documentation: | ||
| 'This command lists all available templates from the default GitHub source ' + | ||
| 'and any additional sources specified with --local-source or --remote-source.' | ||
| 'and any additional sources specified with --local-source or --remote-source. ' + | ||
| 'Use --spfx-version to filter templates by version (e.g., "--spfx-version 1.22").' |
| { | ||
| componentName, | ||
| libraryName: this._libraryNameParameter.value, | ||
| libraryName: this._libraryNameParameter.value || rawSolutionName, |
Comment on lines
+275
to
+276
| 'Scaffold a new React web part in the current working directory:\n spfx create --template webpart-react --component-name "HelloWorld" --library-name "helloworld-library" --solution-name "helloworld" --component-description "A Hello World web part"', | ||
| 'Scaffold an extension with pnpm (skipping npm install):\n spfx create --template extension-field --component-name "ColorField" --package-manager pnpm', |
Comment on lines
+42
to
+46
| const spfxVersion: string | undefined = this._spfxVersionParameter.value?.trim(); | ||
| if (spfxVersion) { | ||
| const filteredTemplates = [...templates.values()].filter( | ||
| (t) => t.spfxVersion && t.spfxVersion.startsWith(spfxVersion) | ||
| ); |
Comment on lines
+195
to
+198
| for (const example of examples) { | ||
| lines.push(''); | ||
| lines.push(` ${example}`); | ||
| } |
Comment on lines
+41
to
+42
| // Apply --spfx-version filter if provided (user expects filter, not just branch selection) | ||
| const spfxVersion: string | undefined = this._spfxVersionParameter.value?.trim(); |
Contributor
Author
Fix SummaryPushed at [
Reviewers: Copilot |
|
@vystartasv seems like this PR has commits from #259 PR |
Adds an abstract getExamples() method to SPFxActionBase that subclasses override to provide usage examples. The renderHelpText() method is overridden to append a formatted EXAMPLES section. Includes 4 examples for the 'spfx create' command covering: - Basic React web part scaffolding - Extension scaffolding with pnpm - Local template source usage - SPFx version targeting Partially addresses SharePoint#238
- Add override keyword to renderHelpText() (required by noImplicitOverride setting) - Add override keyword to CreateAction.getExamples() - Replace --skip-install examples with --package-manager pnpm - Remove unnecessary parameters from examples
The previous fix used /\r$/ which only strips a trailing CR from the last line. For CRLF content, every line except the last retains \r, producing malformed output. Use /\r\n/g to normalize all pairs.
vystartasv
force-pushed
the
fix/238-help-examples
branch
from
July 13, 2026 13:18
466c7c4 to
01eeccd
Compare
Contributor
Author
4 tasks
Comment on lines
+275
to
+278
| 'Scaffold a new React web part in the current working directory:\n spfx create --template webpart-react --component-name "HelloWorld" --library-name "helloworld-library" --solution-name "helloworld" --component-description "A Hello World web part"', | ||
| 'Scaffold an extension with pnpm (skipping npm install):\n spfx create --template extension-field --component-name "ColorField" --package-manager pnpm', | ||
| 'Scaffold a web part without npm install, specifying a local template source:\n spfx create --template webpart-react --component-name "MyWebPart" --library-name "mywebpart" --solution-name "mywebpart" --local-source ./my-templates', | ||
| 'Scaffold a web part using a specific SPFx version:\n spfx create --template webpart-react --component-name "MyWP" --component-description "Description" --spfx-version 1.22' |
Comment on lines
+183
to
+188
| public override renderHelpText(): string { | ||
| const base: string = super.renderHelpText(); | ||
| const examples: string[] = this.getExamples(); | ||
| if (examples.length === 0) { | ||
| return base; | ||
| } |
Comment on lines
+195
to
+198
| for (const example of examples) { | ||
| lines.push(''); | ||
| lines.push(` ${example}`); | ||
| } |
Comment on lines
+1
to
+5
| { | ||
| "changes": [ | ||
| { | ||
| "packageName": "@microsoft/spfx-cli", | ||
| "comment": "", |
Comment on lines
+175
to
+177
| protected getExamples(): string[] { | ||
| return []; | ||
| } |
Comment on lines
+183
to
+187
| public override renderHelpText(): string { | ||
| const base: string = super.renderHelpText(); | ||
| const examples: string[] = this.getExamples(); | ||
| if (examples.length === 0) { | ||
| return base; |
Comment on lines
+190
to
+200
| // Append examples after the last line of base help | ||
| // Normalize Windows CRLF to LF before splitting so every line is clean | ||
| const lines: string[] = base.replace(/\r\n/g, '\n').split('\n'); | ||
| lines.push(''); | ||
| lines.push('EXAMPLES'); | ||
| for (const example of examples) { | ||
| lines.push(''); | ||
| lines.push(` ${example}`); | ||
| } | ||
| lines.push(''); | ||
| return lines.join('\n'); |
Comment on lines
+275
to
+278
| 'Scaffold a new React web part in the current working directory:\n spfx create --template webpart-react --component-name "HelloWorld" --library-name "helloworld-library" --solution-name "helloworld" --component-description "A Hello World web part"', | ||
| 'Scaffold an extension with pnpm (skipping npm install):\n spfx create --template extension-field --component-name "ColorField" --package-manager pnpm', | ||
| 'Scaffold a web part without npm install, specifying a local template source:\n spfx create --template webpart-react --component-name "MyWebPart" --library-name "mywebpart" --solution-name "mywebpart" --local-source ./my-templates', | ||
| 'Scaffold a web part using a specific SPFx version:\n spfx create --template webpart-react --component-name "MyWP" --component-description "Description" --spfx-version 1.22' |
Comment on lines
+273
to
+280
| protected override getExamples(): string[] { | ||
| return [ | ||
| 'Scaffold a new React web part in the current working directory:\n spfx create --template webpart-react --component-name "HelloWorld" --library-name "helloworld-library" --solution-name "helloworld" --component-description "A Hello World web part"', | ||
| 'Scaffold an extension with pnpm (skipping npm install):\n spfx create --template extension-field --component-name "ColorField" --package-manager pnpm', | ||
| 'Scaffold a web part without npm install, specifying a local template source:\n spfx create --template webpart-react --component-name "MyWebPart" --library-name "mywebpart" --solution-name "mywebpart" --local-source ./my-templates', | ||
| 'Scaffold a web part using a specific SPFx version:\n spfx create --template webpart-react --component-name "MyWP" --component-description "Description" --spfx-version 1.22' | ||
| ]; | ||
| } |
iclanton
reviewed
Jul 13, 2026
Comment on lines
+274
to
+279
| return [ | ||
| 'Scaffold a new React web part in the current working directory:\n spfx create --template webpart-react --component-name "HelloWorld" --library-name "helloworld-library" --solution-name "helloworld" --component-description "A Hello World web part"', | ||
| 'Scaffold an extension with pnpm (skipping npm install):\n spfx create --template extension-field --component-name "ColorField" --package-manager pnpm', | ||
| 'Scaffold a web part without npm install, specifying a local template source:\n spfx create --template webpart-react --component-name "MyWebPart" --library-name "mywebpart" --solution-name "mywebpart" --local-source ./my-templates', | ||
| 'Scaffold a web part using a specific SPFx version:\n spfx create --template webpart-react --component-name "MyWP" --component-description "Description" --spfx-version 1.22' | ||
| ]; |
Contributor
There was a problem hiding this comment.
Suggested change
| return [ | |
| 'Scaffold a new React web part in the current working directory:\n spfx create --template webpart-react --component-name "HelloWorld" --library-name "helloworld-library" --solution-name "helloworld" --component-description "A Hello World web part"', | |
| 'Scaffold an extension with pnpm (skipping npm install):\n spfx create --template extension-field --component-name "ColorField" --package-manager pnpm', | |
| 'Scaffold a web part without npm install, specifying a local template source:\n spfx create --template webpart-react --component-name "MyWebPart" --library-name "mywebpart" --solution-name "mywebpart" --local-source ./my-templates', | |
| 'Scaffold a web part using a specific SPFx version:\n spfx create --template webpart-react --component-name "MyWP" --component-description "Description" --spfx-version 1.22' | |
| ]; | |
| const templateParameterName: string = this._solutionNameParameter.longName; | |
| const solutionNameParmeterName: string = this._solutionNameParameter.longName; | |
| const componentDescriptionParameterName: string = this._componentDescriptionParameter.longName; | |
| const componentNameParameterName: string = this._componentNameParameter.longName; | |
| const libraryNameParameterName: string this._libraryNameParameter.longName; | |
| const packageManagerParameterName: string = this._packageManagerParameter.longName; | |
| const spfxVersionParameterName: string = this._spfxVersionParameter.longName; | |
| const localSourceParameterName: string = this._localSourceParameter.longName; | |
| return [ | |
| `Scaffold a new React web part in the current working directory:\n spfx create ${templateParameterName} webpart-react ${componentNameParameterName} "HelloWorld" ${libraryNameParameterName} "helloworld-library" ${solutionNameParmeterName} "helloworld" ${componentDescriptionParameterName} "A Hello World web part"`, | |
| `Scaffold an extension with pnpm (skipping npm install):\n spfx create ${templateParameterName} extension-field ${componentNameParameterName} "ColorField" ${packageManagerParameterName} pnpm`, | |
| `Scaffold a web part without npm install, specifying a local template source:\n spfx create ${templateParameterName} webpart-react ${componentNameParameterName} "MyWebPart" ${libraryNameParameterName} "mywebpart" ${solutionNameParmeterName} "mywebpart" ${localSourceParameterName} ./my-templates`, | |
| `Scaffold a web part using a specific SPFx version:\n spfx create ${templateParameterName} webpart-react ${componentNameParameterName} "MyWP" ${componentDescriptionParameterName} "Description" ${spfxVersionParameterName} 1.22` | |
| ]; |
|
|
||
| // Append examples after the last line of base help | ||
| // Normalize Windows CRLF to LF before splitting so every line is clean | ||
| const lines: string[] = base.replace(/\r\n/g, '\n').split('\n'); |
Contributor
There was a problem hiding this comment.
Why bother splitting this? Just append \nEXAMPLES\n${exampleLines}\n to the base text.
The new EXAMPLES section in renderHelpText() causes the 'create' action help snapshot to diverge from the updated output. Regenerated with --updateSnapshot.
Comment on lines
+183
to
+201
| public override renderHelpText(): string { | ||
| const base: string = super.renderHelpText(); | ||
| const examples: string[] = this.getExamples(); | ||
| if (examples.length === 0) { | ||
| return base; | ||
| } | ||
|
|
||
| // Append examples after the last line of base help | ||
| // Normalize Windows CRLF to LF before splitting so every line is clean | ||
| const lines: string[] = base.replace(/\r\n/g, '\n').split('\n'); | ||
| lines.push(''); | ||
| lines.push('EXAMPLES'); | ||
| for (const example of examples) { | ||
| lines.push(''); | ||
| lines.push(` ${example}`); | ||
| } | ||
| lines.push(''); | ||
| return lines.join('\n'); | ||
| } |
Fixes two issues: 1. Reverts --library-name back to optional (regression from merge conflict with already-merged PR SharePoint#260 that made it optional on main) 2. Fixes example text to accurately describe CLI behavior: - Subfolder output, not CWD - Use --package-manager none (not pnpm) to skip install - Include required params in all examples now that --library-name is optional, examples show the minimal arguments needed Co-Authored-By: Claw <claw@hermes>
Comment on lines
+61
to
+64
| EXAMPLES | ||
|
|
||
| Create a new React web part. Scaffolds into a subfolder named after the solution: | ||
| spfx create --template webpart-react --component-name \"HelloWorld\" --solution-name \"helloworld\" --component-description \"A Hello World web part\" |
Comment on lines
83
to
+87
| this._libraryNameParameter = this.defineStringParameter({ | ||
| parameterLongName: '--library-name', | ||
| argumentName: 'LIBRARY_NAME', | ||
| description: 'The library name for the component', | ||
| required: true | ||
| description: 'The library name for the component. Defaults to the solution name if not specified.', | ||
| required: false |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds an extensible usage examples framework to the SPFx CLI help output:
SPFxActionBase — new abstract method
getExamples(): string[]that subclasses override to provide usage examples. OverridesrenderHelpText()to append a formatted EXAMPLES section after the default help text.CreateAction — 4 examples covering the key scaffolding scenarios:
Partially addresses #238
How was this tested?
mainto remove earlier cross-PR contaminationType of change