feat: add usage examples to CLI help output#264
Open
vystartasv wants to merge 7 commits into
Open
Conversation
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.
- Example 1: removed misleading 'in the current working directory' phrasing - Example 2: fixed description — pnpm installs deps, doesn't skip them - Example 4: added --target-dir . so the intent is explicit - All examples now match actual CLI behavior
4 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an action-level “usage examples” extension point to the SPFx CLI help output, and wires up initial spfx create examples to demonstrate common scaffolding scenarios.
Changes:
- Introduces
getExamples()onSPFxActionBaseand appends anEXAMPLESsection to action help when provided. - Adds four
spfx createusage examples viaCreateAction.getExamples(). - Adds a Rush change file for
@microsoft/spfx-cli(typenone).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| common/changes/@microsoft/spfx-cli/help-examples_2026-07-13.json | Adds change metadata for the CLI help output enhancement. |
| apps/spfx-cli/src/cli/actions/SPFxActionBase.ts | Adds an examples hook and extends help rendering to include an EXAMPLES section. |
| apps/spfx-cli/src/cli/actions/CreateAction.ts | Provides initial spfx create examples for the new help framework. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+273
to
+280
| protected override getExamples(): string[] { | ||
| return [ | ||
| 'Scaffold a new React web part for SharePoint:\n spfx create --template webpart-react --component-name "HelloWorld" --library-name "helloworld-library" --solution-name "helloworld" --component-description "A Hello World web part"', | ||
| 'Scaffold a field customizer extension using pnpm for dependency installation:\n spfx create --template extension-field --component-name "ColorField" --package-manager pnpm', | ||
| 'Scaffold a web part without running 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 for a specific SPFx version, writing output to a custom directory:\n spfx create --template webpart-react --component-name "MyWP" --component-description "Description" --spfx-version 1.22 --target-dir ./my-webpart' | ||
| ]; | ||
| } |
Comment on lines
+190
to
+199
| // 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(''); |
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; | ||
| } |
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, with initial examples for the
spfx createaction.Changes:
SPFxActionBase.ts— addsgetExamples()virtual method (default: empty array, returns[]) andrenderHelpText()override that appends a formattedEXAMPLESsection to action help output when examples are defined. Handles CRLF normalization and proper indentation for multi-line examples.CreateAction.ts— implementsgetExamples()with four representative usage examples covering: React web part scaffolding, field customizer with pnpm, local template sources, and SPFx version targeting with custom output directory.Scope: This PR is strictly limited to the help examples framework. It does NOT modify CLI semantics, parameter requirements, or template filtering behavior.
How was this tested?
tsc --noEmitpasses (no type errors,overridekeywords present)getExamples()returns empty array by default, so existing actions are unaffectedheft test --clean -uType of change
Change file
common/changes/@microsoft/spfx-cli/help-examples_2026-07-13.json— type:"none"(pre-initial release)