Adds JSON output mode for the `spfx list-templates` command. Closes #235 by Adam-it · Pull Request #253 · SharePoint/spfx

Adam-it · 2026-04-25T19:56:07Z

Description

The aim is to:

introduce output option for the list-templates command that supports JSON (which will be the default mode) and TEXT.
added --verbose flag and moved some of the information command outputs to be part of the verbose, so that they are not part of stdout but instead are present in stderr

How was this tested?

added new unit tests for the new functionality
checked locally, see the result below with description

Result

Help now also has new --output and --verbose flag

The default output mode of the list-templates command is now JSON, or you may use the --output json as well

text works as before but --output text needs to be used

Command output is part of stdout, and all other messages go to stderr

To see additional info the --verbose option needs to be used

Type of change

Bug fix
New feature / enhancement -> Closes Introduce JSON output mode for the spfx list-templates command #235
Template change
Documentation / CI / governance

Copilot

Pull request overview

Adds a JSON output mode (now the default) for spfx list-templates, and refactors command output so structured results go to stdout while informational output is routed to stderr.

Changes:

Added --output/-o {json,text} to list-templates, defaulting to json
Implemented JSON serialization for template collections (toJsonString()) and updated CLI action to write JSON to stdout
Introduced StderrTerminalProvider and added/updated unit tests + docs/snapshots accordingly

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
common/changes/@microsoft/spfx-cli/json-output-mode_2026-04-25.json	Adds a change record for the CLI package.
apps/spfx-cli/src/utilities/StderrTerminalProvider.ts	New terminal provider intended to route CLI messages to stderr for JSON output scenarios.
apps/spfx-cli/src/utilities/tests/StderrTerminalProvider.test.ts	Unit tests validating stderr routing behavior.
apps/spfx-cli/src/cli/actions/ListTemplatesAction.ts	Adds `--output` option; writes JSON to stdout by default and table output for text mode.
apps/spfx-cli/src/cli/actions/SPFxActionBase.ts	Makes `_terminal` mutable so actions can temporarily swap terminal behavior.
apps/spfx-cli/src/cli/actions/tests/ListTemplatesAction.test.ts	Updates existing tests to force text output; adds JSON-output tests using stdout spying.
apps/spfx-cli/src/cli/test/snapshots/CommandLineHelp.test.ts.snap	Updates help snapshot to include the new `--output` parameter and its description.
apps/spfx-cli/README.md	Documents `--output` and provides examples for JSON (default) and text.
api/spfx-template-api/src/repositories/SPFxTemplateCollection.ts	Adds `toJsonString()` for structured template list serialization.
api/spfx-template-api/src/repositories/test/SPFxTemplateCollection.test.ts	Adds unit tests for `toJsonString()`.
api/spfx-template-api/src/repositories/test/snapshots/SPFxTemplateCollection.test.ts.snap	Snapshot for JSON serialization formatting.
api/spfx-template-api/etc/spfx-template-api.api.md	API report update to include `toJsonString()`.
api/spfx-template-api/README.md	Updates docs to mention JSON/table output helpers.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

apps/spfx-cli/README.md:81

The spfx list-templates docs list the new --output option, but the command also now supports --verbose (and help output advertises it). The README’s optional flags table should include --verbose and clarify that verbose/info messages are written to stderr (especially important with JSON output).

### Optional flags

| Flag | Default | Description |
|------|---------|-------------|
| `-o`, `--output {json,text}` | `json` | Output format. `json` writes machine-readable JSON to stdout (informational messages go to stderr). `text` writes a human-readable table |
| `--spfx-version VERSION` | `version/latest` branch | Branch/tag in the default template repo to use (e.g. `1.22`, `1.23-rc.0`) |
| `--template-url URL` | `https://github.com/SharePoint/spfx` | Custom GitHub template repository (default source) |
| `--local-source PATH` | — | Path to a local template folder to include (repeatable) |
| `--remote-source URL` | — | Additional public GitHub repo to include as a template source (repeatable) |

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

iclanton · 2026-06-03T22:32:10Z

+// @public
+export interface ITemplateJsonOutputEntry {
+    // (undocumented)
+    category: string;


Can this be a type union?

iclanton · 2026-06-03T22:32:27Z

+    // (undocumented)
+    category: string;
+    // (undocumented)
+    description: string | null;


We generally use undefined for nullish things, not null.

iclanton · 2026-06-03T22:33:46Z

+  // `null` (not `undefined`) is intentional: JSON.stringify drops `undefined` fields
+  // but preserves `null`, ensuring the field is always present in the output.
+  // eslint-disable-next-line @rushstack/no-new-null


We could also just make this required.

iclanton · 2026-06-03T22:34:05Z

+ * {@link SPFxTemplateCollection.toJsonString}.
+ */
+export interface ITemplateJsonOutputEntry {
+  name: string;


Add doc comments for these things. It's not obvious what version is supposed to be, for example.

iclanton · 2026-06-03T22:34:32Z

 Array [
-  "[    log] Using GitHub template source: https://github.com/SharePoint/spfx[n]",
-  "[    log] Adding local template source: /path/to/templates[n]",
+  "[verbose] Using GitHub template source: https://github.com/SharePoint/spfx[n]",


Unrelated change?

iclanton · 2026-06-03T22:34:51Z

+      expect(parsed).toEqual([
+        {
+          name: 'webpart-minimal',
+          category: 'webpart',
+          description: 'A minimal web part template (no framework) for SPFx',
+          version: '0.0.1',
+          spfxVersion: '1.22.2',
+          fileCount: 23
+        }
+      ]);
+    });


Just make this a snapshot?

iclanton · 2026-06-03T22:35:22Z

+    it('does not write table output to the terminal', async () => {
+      const { terminalChunks } = await runListJsonAsync();
+      const hasTableOutput: boolean = terminalChunks.some(
+        (chunk: string) => chunk.includes('┌') || chunk.includes('Found')
+      );
+      expect(hasTableOutput).toBe(false);
+    });


This is redundant with the parsing test.

iclanton · 2026-06-03T22:36:40Z

+  "changes": [
+    {
+      "packageName": "@microsoft/spfx-cli",
+      "comment": "Adds JSON output mode for the `spfx list-templates` command (default `--output json`, with `--output text` for the human-readable table). Also adds a global `--verbose` flag to all actions and demotes source-registration messages (`Using GitHub template source`, `Adding local template source`, `Adding remote template source`) to verbose-level output.",


Stick the note about --verbose in a separate changelog message.

iclanton · 2026-06-03T22:37:30Z

+        'Output format. "json" writes machine-readable JSON to stdout (informational ' +
+        'messages go to stderr). "text" writes a human-readable table.',


Generally avoid printing non-erroneous data to stderr. In JSON mode, why not just not output anything that can't be JSON-parsed?

iclanton · 2026-06-03T22:37:56Z

      terminal
    );
+
+    this._outputParameter = this.defineChoiceParameter({


Consider making this a --json flag instead.

Copilot AI review requested due to automatic review settings April 25, 2026 19:56

Copilot started reviewing on behalf of Adam-it April 25, 2026 19:56 View session

Copilot AI reviewed Apr 25, 2026

View reviewed changes

Comment thread apps/spfx-cli/src/cli/actions/ListTemplatesAction.ts Outdated

Comment thread apps/spfx-cli/src/utilities/StderrTerminalProvider.ts Outdated

Comment thread apps/spfx-cli/src/cli/actions/tests/ListTemplatesAction.test.ts Outdated

Adam-it marked this pull request as draft April 25, 2026 20:48

Adam-it force-pushed the adds-json-output-mode branch from 26860dd to 65b297d Compare April 25, 2026 21:37

Adam-it marked this pull request as ready for review April 25, 2026 21:38

Copilot AI review requested due to automatic review settings April 25, 2026 21:38

Copilot started reviewing on behalf of Adam-it April 25, 2026 21:39 View session

Copilot AI reviewed Apr 25, 2026

View reviewed changes

Comment thread apps/spfx-cli/src/cli/actions/ListTemplatesAction.ts Outdated

Adds json output mode for list templates command

77d8b1c

Adam-it force-pushed the adds-json-output-mode branch from 9e88690 to 77d8b1c Compare April 25, 2026 21:57

iclanton reviewed Jun 3, 2026

View reviewed changes

		'Output format. "json" writes machine-readable JSON to stdout (informational ' +
		'messages go to stderr). "text" writes a human-readable table.',

Conversation

Adam-it commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

How was this tested?

Result

Type of change

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Adam-it commented Apr 25, 2026 •

edited

Loading