--spfx-version resolves to version/<VERSION> branch (#177)

## Description

Updates `--spfx-version` so the value is used as a `version/<VERSION>`
branch name in the template repository. For example, `--spfx-version
1.22` now resolves to the `version/1.22` branch instead of `1.22`.

Updates parameter description, README, and tests accordingly.

## How was this tested

- `heft test` passes (46 tests)

## Type of change

- [ ] Bug fix
- [x] New feature / behavior change
- [ ] Template change (templates/ or examples/)
- [ ] Docs / CI only

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: iclanton

apps/spfx-cli/README.md

@@ -45,7 +45,7 @@ Scaffolds a new SPFx component. Templates are pulled from the [SharePoint/spfx](
 | `--solution-name NAME` | kebab-cased component name | SharePoint solution name |
 | `--component-alias ALIAS` | same as `--component-name` | Short identifier for the component |
 | `--component-description TEXT` | `"<name> description"` | Component description string |
-| `--spfx-version VERSION` | repo default branch | Branch/tag in the template repo to use (e.g. `1.22`, `1.23-rc.0`) |
+| `--spfx-version VERSION` | repo default branch | SPFx version to use; resolves to the `version/<VERSION>` branch (e.g. `1.22`, `1.23-rc.0`) |
 | `--template-url URL` | `https://github.com/SharePoint/spfx` | Custom GitHub template repository |
 | `--local-template PATH` | — | Path to a local template folder (repeatable; bypasses GitHub) |
 
@@ -60,7 +60,7 @@ Scaffolds a new SPFx component. Templates are pulled from the [SharePoint/spfx](
 
 ## Templates
 
-Templates are fetched at runtime from the [SharePoint/spfx](https://github.com/SharePoint/spfx) GitHub repository. Use `--spfx-version` to target a specific release branch, or `--local-template` to use templates from disk.
+Templates are fetched at runtime from the [SharePoint/spfx](https://github.com/SharePoint/spfx) GitHub repository. Use `--spfx-version` to target a specific release branch (e.g. `--spfx-version 1.22` resolves to the `version/1.22` branch), or `--local-template` to use templates from disk.
 
 ### Web Parts
 

apps/spfx-cli/src/cli/actions/CreateAction.ts

@@ -137,8 +137,8 @@ export class CreateAction extends CommandLineAction {
       parameterLongName: '--spfx-version',
       argumentName: 'VERSION',
       description:
-        'The branch name in the template repository to use (e.g., "1.22", "1.23-rc.0"). ' +
-        "Defaults to the repository's default branch (main)."
+        'The SPFx version to use (e.g., "1.22", "1.23-rc.0"). Resolves to the "version/<VERSION>" branch ' +
+        "in the template repository. Defaults to the repository's default branch (main)."
     });
 
     this._packageManagerParameter = this.defineChoiceParameter({
@@ -184,14 +184,24 @@ export class CreateAction extends CommandLineAction {
         const rawUrl: string = (this._templateUrlParameter.value ?? '').trim() || DEFAULT_GITHUB_REPO;
         const { repoUrl, urlBranch } = parseGitHubUrlAndRef(rawUrl);
 
-        const spfxVersion: string | undefined = this._spfxVersionParameter.value;
-        if (spfxVersion !== undefined && urlBranch !== undefined) {
+        const spfxVersionRaw: string | undefined = this._spfxVersionParameter.value?.trim();
+        let spfxVersionBranch: string | undefined;
+        if (spfxVersionRaw) {
+          if (spfxVersionRaw.startsWith('version/')) {
+            spfxVersionBranch = spfxVersionRaw;
+          } else {
+            spfxVersionBranch = `version/${spfxVersionRaw}`;
+          }
+        }
+
+        if (spfxVersionBranch && urlBranch) {
           terminal.writeWarningLine(
             `${this._templateUrlParameter.longName} contains a branch ('/tree/${urlBranch}'). ` +
-              `${this._spfxVersionParameter.longName} "${spfxVersion}" will take precedence.`
+              `${this._spfxVersionParameter.longName} "${spfxVersionRaw}" will take precedence.`
           );
         }
-        const ref: string | undefined = spfxVersion ?? urlBranch;
+
+        const ref: string | undefined = spfxVersionBranch ?? urlBranch;
 
         terminal.writeLine(`Using GitHub template source: ${repoUrl}${ref ? ` (branch: ${ref})` : ''}`);
         manager.addSource(new PublicGitHubRepositorySource(repoUrl, ref, this._terminal));

apps/spfx-cli/src/cli/actions/tests/CreateAction.test.ts

@@ -226,7 +226,7 @@ describe('CreateAction', () => {
       await runCreateAsync(['--spfx-version', '1.22']);
       expect(MockedGitHub).toHaveBeenCalledWith(
         'https://github.com/SharePoint/spfx',
-        '1.22',
+        'version/1.22',
         expect.anything()
       );
     });
@@ -236,7 +236,7 @@ describe('CreateAction', () => {
       await runCreateAsync(['--spfx-version', '1.22']);
       expect(MockedGitHub).toHaveBeenCalledWith(
         'https://github.com/my-org/my-templates',
-        '1.22',
+        'version/1.22',
         expect.anything()
       );
     });
@@ -247,7 +247,7 @@ describe('CreateAction', () => {
       await runCreateAsync(['--spfx-version', '1.22']);
       expect(MockedGitHub).toHaveBeenCalledWith(
         'https://github.com/SharePoint/spfx',
-        '1.22',
+        'version/1.22',
         expect.anything()
       );
     });

apps/spfx-cli/src/cli/actions/tests/__snapshots__/CreateAction.test.ts.snap

@@ -101,7 +101,7 @@ Array [
 
 exports[`CreateAction --spfx-version passes ref to PublicGitHubRepositorySource when --spfx-version is set 1`] = `
 Array [
-  "[    log] Using GitHub template source: https://github.com/SharePoint/spfx (branch: 1.22)[n]",
+  "[    log] Using GitHub template source: https://github.com/SharePoint/spfx (branch: version/1.22)[n]",
   "[    log] [Mocked SPFxTemplateCollection][n]",
   "[    log] targetDir: /tmp/test[n]",
   "[    log] [n]",
@@ -112,7 +112,7 @@ Array [
 
 exports[`CreateAction --spfx-version passes ref when SPFX_TEMPLATE_REPO_URL and --spfx-version are both set 1`] = `
 Array [
-  "[    log] Using GitHub template source: https://github.com/my-org/my-templates (branch: 1.22)[n]",
+  "[    log] Using GitHub template source: https://github.com/my-org/my-templates (branch: version/1.22)[n]",
   "[    log] [Mocked SPFxTemplateCollection][n]",
   "[    log] targetDir: /tmp/test[n]",
   "[    log] [n]",
@@ -124,7 +124,7 @@ Array [
 exports[`CreateAction --spfx-version uses --spfx-version over branch encoded in SPFX_TEMPLATE_REPO_URL /tree/ path 1`] = `
 Array [
   "[warning] --template-url contains a branch ('/tree/pending-fixes'). --spfx-version \\"1.22\\" will take precedence.[n]",
-  "[    log] Using GitHub template source: https://github.com/SharePoint/spfx (branch: 1.22)[n]",
+  "[    log] Using GitHub template source: https://github.com/SharePoint/spfx (branch: version/1.22)[n]",
   "[    log] [Mocked SPFxTemplateCollection][n]",
   "[    log] targetDir: /tmp/test[n]",
   "[    log] [n]",

apps/spfx-cli/src/cli/test/__snapshots__/CommandLineHelp.test.ts.snap

@@ -41,9 +41,10 @@ Optional arguments:
                         may alternatively be specified via the
                         SPFX_TEMPLATE_REPO_URL environment variable.
   --spfx-version VERSION
-                        The branch name in the template repository to use (e.
-                        g., \\"1.22\\", \\"1.23-rc.0\\"). Defaults to the
-                        repository's default branch (main).
+                        The SPFx version to use (e.g., \\"1.22\\", \\"1.23-rc.0\\").
+                        Resolves to the \\"version/<VERSION>\\" branch in the
+                        template repository. Defaults to the repository's
+                        default branch (main).
   --package-manager {npm,pnpm,yarn,none}
                         Package manager to use for dependency installation
                         after scaffolding. Use \\"none\\" to skip installation.

common/changes/@microsoft/spfx-cli/version-branch-prefix_2026-03-24.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/spfx-cli",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/spfx-cli"
+}