@spfx-fast/spfx-workbench 0.1.3 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +17 -10
- package/package.json +1 -1
- package/scripts/diagnose-consumer.mjs +8 -10
- package/scripts/spfx-node-runtime.mjs +3 -3
package/README.md
CHANGED
|
@@ -1,8 +1,15 @@
|
|
|
1
1
|
# SPFx Workbench
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Build and debug SharePoint Framework (SPFx) components with a local preview, focused diagnostics, and tools for working with real SharePoint behavior. Workbench can replay captured API responses, reuse an existing browser storage state, and coordinate the project's Heft workflow.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Start with the [IDE router](packages/ide/README.md) for the agent workflow, or install Workbench directly in an SPFx project:
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm install --save-dev @spfx-fast/spfx-workbench
|
|
9
|
+
npx spfx-workbench --component src/components/HelloWorld.tsx
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
The local canvas is a fast development aid, not a full SharePoint host. It renders compatible React components and a documented subset of SPFx lifecycle/context behavior; use the real SharePoint page when validating host integration. Workbench is a developer tool, not a security or credential scanner.
|
|
6
13
|
|
|
7
14
|
## Run locally
|
|
8
15
|
|
|
@@ -31,14 +38,14 @@ The portable `spfx-ide` skill ships in [`packages/ide/skills/spfx-ide/SKILL.md`]
|
|
|
31
38
|
|
|
32
39
|
## Preview a consumer component
|
|
33
40
|
|
|
34
|
-
The npm package name is `@spfx-fast/spfx-workbench`.
|
|
41
|
+
The npm package name is `@spfx-fast/spfx-workbench`. Install it in an SPFx project and run the CLI from that project's root:
|
|
35
42
|
|
|
36
43
|
```sh
|
|
37
44
|
npm install --save-dev @spfx-fast/spfx-workbench
|
|
38
45
|
npx spfx-workbench --component src/components/HelloWorld.tsx
|
|
39
46
|
```
|
|
40
47
|
|
|
41
|
-
|
|
48
|
+
To test changes from this repository, install the local repository path instead.
|
|
42
49
|
|
|
43
50
|
The registry install command is:
|
|
44
51
|
|
|
@@ -68,13 +75,13 @@ Inspect the consumer's installed runtime versions and an optional component entr
|
|
|
68
75
|
npx spfx-workbench-doctor --component src/components/HelloWorld.tsx --props-file .spfx-workbench/preview-props.json
|
|
69
76
|
```
|
|
70
77
|
|
|
71
|
-
The command emits JSON with per-check `supported`, `unsupported`, or `unknown` status plus mock coverage and provenance. For a props file, it reports the project-relative path and property names, never values, and flags a `context` override. It scans installed `@microsoft/sp-*` packages, including nested `node_modules`,
|
|
78
|
+
The command emits JSON with per-check `supported`, `unsupported`, or `unknown` status plus mock coverage and provenance. For a props file, it reports the project-relative path and property names, never values, and flags a `context` override. It scans installed `@microsoft/sp-*` packages, including nested `node_modules`, accepts SPFx 1.x packages and reports package alignment separately. React 17 and 18 are recognized; other versions are flagged for review. Microsoft’s documented SPFx 1.24.1 Node.js range (22.14+ within 22.x, 24.x, or 26.x) is advisory and unknown for other releases. It never blocks Workbench on a consumer Node mismatch. Workbench itself requires Node `^20.19.0 || >=22.12.0` for Vite 8. The Heft launcher uses the consumer’s installed CLI without a version pin and applies to Heft-based SPFx projects (1.22+); older Gulp-era projects can use preview on a best-effort basis. Missing package metadata is `unknown` and summarized as incomplete. It does not test every SPFx behavior or infer component prop types/API usage.
|
|
72
79
|
|
|
73
80
|
This is an early consumer-loader slice. It supports explicit JSON props and the documented read-only simulator context subset; it does not create full SPFx host context or infer an arbitrary TypeScript props contract. Broader SPFx compatibility checks and live SharePoint validation remain incomplete.
|
|
74
81
|
|
|
75
82
|
## How this fits with the SPFx Fast tools
|
|
76
83
|
|
|
77
|
-
Use [`@spfx-fast/ide`](packages/ide/README.md) as the thin developer and agent entry point.
|
|
84
|
+
Use [`@spfx-fast/ide`](packages/ide/README.md) as the thin developer and agent entry point. The `spfx-ide` CLI routes to focused tools; installation as a project devDependency or globally places Agent Skills guidance in supported skill directories unless lifecycle scripts are disabled. This confirms file placement, not discovery by every agent; check the agent's own skills list where available. Global CLI use also needs npm's global bin directory on `PATH`. Workbench owns component preview, synthetic context/API replay, diagnostics, capture, and Heft launch. The focused companion packages have separate jobs:
|
|
78
85
|
|
|
79
86
|
- [`@spfx-fast/playwright`](https://www.npmjs.com/package/%40spfx-fast/playwright) runs authenticated browser tests against a real SharePoint page.
|
|
80
87
|
- [`@spfx-fast/knowledge`](https://www.npmjs.com/package/%40spfx-fast/knowledge) provides the SPFx agent skill and debugging references; use it to guide the tools, not as a runtime dependency.
|
|
@@ -192,7 +199,7 @@ Verify React Fast Refresh in a real browser with:
|
|
|
192
199
|
npm run check:browser-hmr
|
|
193
200
|
```
|
|
194
201
|
|
|
195
|
-
The check uses Playwright-managed Chromium, installed on first use, and does not require a system Chrome path. It edits a synthetic consumer component 20 times at a 1023 px viewport and confirms each React update applies, component state survives every edit, and the page does not navigate. It then adds an incompatible named export and confirms Vite reports the boundary reason, the browser reloads once, and the updated component appears. It reports min, median, p95, and max for compatible browser updates; it does not measure the full developer workflow or SharePoint. Set `--samples` to an integer from 1 to 100. `npm run check:responsive` additionally checks the five local section-width options with a synthetic web part at nine viewport widths and verifies the insertion control on touch input. `npm run check:release` runs the local gates, browser HMR check, and responsive layout check. It still does not start real Heft
|
|
202
|
+
The check uses Playwright-managed Chromium, installed on first use, and does not require a system Chrome path. It edits a synthetic consumer component 20 times at a 1023 px viewport and confirms each React update applies, component state survives every edit, and the page does not navigate. It then adds an incompatible named export and confirms Vite reports the boundary reason, the browser reloads once, and the updated component appears. It reports min, median, p95, and max for compatible browser updates; it does not measure the full developer workflow or SharePoint. Set `--samples` to an integer from 1 to 100. `npm run check:responsive` additionally checks the five local section-width options with a synthetic web part at nine viewport widths and verifies the insertion control on touch input. `npm run check:release` runs the local gates, browser HMR check, and responsive layout check. It still does not start real Heft or establish tenant parity.
|
|
196
203
|
|
|
197
204
|
Measure that endpoint while the dev server is running:
|
|
198
205
|
|
|
@@ -228,7 +235,7 @@ When the page is in edit mode during an SPFx debug session, the [SharePoint Fram
|
|
|
228
235
|
|
|
229
236
|
## Project status
|
|
230
237
|
|
|
231
|
-
See [the engineering report](reports/sharepoint-simulator-engineering-report.html) for
|
|
238
|
+
See [the engineering report](reports/sharepoint-simulator-engineering-report.html) for implementation evidence, unmeasured baselines, and known gaps. [Local section measurements](reports/section-layout-sizes.html) list the synthetic editor's section/web-part dimensions; [tenant page measurements](reports/tenant-page-layout-sizes.html) list read-only live view-mode section/ControlZone boxes at nine viewport widths.
|
|
232
239
|
|
|
233
240
|
Run the automated local release checks together with:
|
|
234
241
|
|
|
@@ -238,12 +245,12 @@ npm run check:local
|
|
|
238
245
|
|
|
239
246
|
This builds the workbench, runs `npm test` (temporary-consumer regressions and a synthetic local-CDP auth capture check), measures 20 consumer Vite HMR events, and installs the clean npm tarball into a disposable consumer. It does not verify browser React apply/state retention; use `npm run check:release` for the additional Chrome gate. Neither command proves a real Heft session, live-page parity, or every release criterion below.
|
|
240
247
|
|
|
241
|
-
|
|
248
|
+
Inspect the packed package in a clean temporary consumer:
|
|
242
249
|
|
|
243
250
|
```sh
|
|
244
251
|
npm run check:tarball
|
|
245
252
|
```
|
|
246
253
|
|
|
247
|
-
This packs the
|
|
254
|
+
This packs the source manifest, checks every packed path against `package.json` `files`, requires consumer docs/fixtures/source and all declared binaries, verifies the MIT license matches the installed tarball and manifest, and checks that the Node.js engine range survives packing. It installs the package as a devDependency, checks each npm command shim, launches the packaged preview with a synthetic consumer component and props file, verifies the context wrapper, captured HAR response replay, and synthetic fallback, runs compact HAR diff through the installed capture command, and confirms tests, reports, captures, and specs are absent. Its JSON result includes package contents/license checks, packaged diff results, and install/time-to-first-usable-preview timings. The engineering report records setup timings against artifact hashes; these local warm-cache samples do not establish a general setup success rate or baseline comparison.
|
|
248
255
|
|
|
249
256
|
Original simulator code is MIT licensed; see [LICENSE](LICENSE).
|
package/package.json
CHANGED
|
@@ -68,10 +68,10 @@ function checkVersion(name, version, supported) {
|
|
|
68
68
|
const match = /^(\d+)\.(\d+)\.(\d+)(?:\+.*)?$/.exec(version);
|
|
69
69
|
if (!match) return { name, status: 'unknown', version, expected: supported };
|
|
70
70
|
const [major, minor, patch] = match.slice(1).map(Number);
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
return { name, status:
|
|
71
|
+
if (name.startsWith('@microsoft/sp-')) {
|
|
72
|
+
return { name, status: major === 1 ? 'supported' : 'unsupported', version, expected: supported };
|
|
73
|
+
}
|
|
74
|
+
return { name, status: major === 17 || major === 18 ? 'supported' : 'unknown', version, expected: supported };
|
|
75
75
|
}
|
|
76
76
|
|
|
77
77
|
async function diagnose() {
|
|
@@ -100,13 +100,13 @@ async function diagnose() {
|
|
|
100
100
|
const results = [
|
|
101
101
|
...spfxPackages.map((name) => {
|
|
102
102
|
const versions = spfxByName[name];
|
|
103
|
-
const checks = versions.map((version) => checkVersion(name, version, 'SPFx 1.
|
|
103
|
+
const checks = versions.map((version) => checkVersion(name, version, 'SPFx 1.x; Heft-based launcher applies from 1.22'));
|
|
104
104
|
return {
|
|
105
105
|
name,
|
|
106
106
|
status: checks.length === 0 ? 'unknown' : checks.every((check) => check.status === 'supported') ? 'supported' : 'unsupported',
|
|
107
107
|
version: versions.length === 1 ? versions[0] : null,
|
|
108
108
|
versions,
|
|
109
|
-
expected: 'SPFx 1.
|
|
109
|
+
expected: 'SPFx 1.x; Heft-based launcher applies from 1.22',
|
|
110
110
|
};
|
|
111
111
|
}),
|
|
112
112
|
checkVersion('react', reactVersion, '18.3.1'),
|
|
@@ -126,12 +126,10 @@ async function diagnose() {
|
|
|
126
126
|
? 'unknown'
|
|
127
127
|
: spfxByName['@microsoft/sp-webpart-base'].every((version) => version === '1.24.1')
|
|
128
128
|
? 'supported'
|
|
129
|
-
:
|
|
130
|
-
? 'unsupported'
|
|
131
|
-
: 'unknown',
|
|
129
|
+
: 'unknown',
|
|
132
130
|
versions: spfxByName['@microsoft/sp-webpart-base'] ?? [],
|
|
133
131
|
sourceVersion: MOCK_COVERAGE.context.version,
|
|
134
|
-
expected: 'context declaration coverage is verified for SPFx 1.24.1; source review is required for other
|
|
132
|
+
expected: 'context declaration coverage is verified for SPFx 1.24.1; source review is required for other releases',
|
|
135
133
|
},
|
|
136
134
|
];
|
|
137
135
|
if (componentArg) {
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
const SOURCE = 'https://learn.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-development-environment';
|
|
2
2
|
const EXPECTED = 'SPFx 1.24.1 supports Node.js 22.14.0 or later within 22.x, 24.x, and 26.x';
|
|
3
3
|
|
|
4
|
-
/**
|
|
4
|
+
/** Reports Microsoft runtime guidance without blocking the local Workbench preview. */
|
|
5
5
|
export function checkSPFxNodeRuntime(spfxVersion, nodeVersion) {
|
|
6
6
|
const result = { name: 'spfx-node-runtime', spfxVersion: spfxVersion ?? null, nodeVersion: nodeVersion ?? null, expected: EXPECTED, source: SOURCE };
|
|
7
7
|
if (spfxVersion !== '1.24.1') {
|
|
@@ -13,7 +13,7 @@ export function checkSPFxNodeRuntime(spfxVersion, nodeVersion) {
|
|
|
13
13
|
const supported = (major === 22 && minor >= 14) || major === 24 || major === 26;
|
|
14
14
|
return {
|
|
15
15
|
...result,
|
|
16
|
-
status: supported ? 'supported' : '
|
|
17
|
-
reason: supported ? 'The active Node.js major/minor is listed by Microsoft for SPFx 1.24.1.' : 'The active Node.js major/minor is
|
|
16
|
+
status: supported ? 'supported' : 'unknown',
|
|
17
|
+
reason: supported ? 'The active Node.js major/minor is listed by Microsoft for SPFx 1.24.1.' : 'The active Node.js major/minor is outside Microsoft’s listed range; this advisory does not block Workbench.',
|
|
18
18
|
};
|
|
19
19
|
}
|