feat: add SPFx environment setup reference - #5
feat: add SPFx environment setup reference#5Vilius Vystartas (vystartasv) wants to merge 1 commit into
Conversation
Adds setup.md reference covering: - Node.js version detection and compatibility matrix - nvm installation and version switching - Global dependency validation - CLI for Microsoft 365 setup - spfx doctor environment validation - Project-specific SPFx version detection - Full environment setup from scratch - Edge cases (on-premises, permission errors, multiple Node versions) Updates SKILL.md to route setup/environment queries to the new reference. Closes SharePoint#2
Adam Wójcik (Adam-it)
left a comment
Adam Wójcik (Adam-it)
left a comment
There was a problem hiding this comment.
Vilius Vystartas (@vystartasv) Thanks for being eager in helping out but again I suspect you missed the step to validate and read the AI generated content, if that is so, please just stop.
Many of the parts contradict which what I agreed with one of the maintainers of this repo that should be performed or rechecked. The skill is not precise and has many misleading steps and/or just mistakes.
Since I do not own this repo I will leave the decision to the maintainers of the repo what to do with this PR and for now stop my work on this issue.
Kinda demotivating IMO 😟, also since I also started working on this.
| **If Node.js is installed** → check the version against the SPFx compatibility matrix: | ||
|
|
||
| | SPFx version | Node.js version | NPM version | | ||
| |---|---|---| | ||
| | **v1.20 – v1.21.1** | **Node.js v18** | npm v9 – v10 | | ||
| | **v1.22.0+** | **Node.js v18 or v20** | npm v9 – v10 | | ||
| | **v1.23.0+** | **Node.js v20 or v22** | npm v10 – v11 | | ||
|
|
||
| > Source: [Microsoft Learn — SPFx compatibility matrix](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/compatibility) | ||
|
|
||
| **If no SPFx version is specified** → assume the **latest stable** (currently v1.23.x) and check against Node.js v20/v22. | ||
|
|
||
| **If a specific SPFx version is given** (e.g. "SPFx v1.18" or "the first version with form customizers") → look up which SPFx version introduced the feature: |
There was a problem hiding this comment.
In the issue discussion, I agreed with one of the maintainers that using the compatibility table from MS learn is not the way to go as the matrix is incomplete. For example, it does not have the required version of yo or gulp/heft that is required.
| | Feature | First SPFx version | | ||
| |---|---| | ||
| | Web parts | v1.0 | | ||
| | Extensions (field customizers, list view commands) | v1.4 | | ||
| | **Form customizers** | **v1.6** | | ||
| | Adaptive Card Extensions (ACEs) | v1.13 | | ||
| | Heft toolchain | v1.22 | |
There was a problem hiding this comment.
We also agreed that there is no need to keep track of versions that brought bigger features, as it was described as 'trivia'. But here we store a talbe that points out when something, like form customizers, was introduced
|
|
||
| --- | ||
|
|
||
| ## 2. Node.js Version Manager (nvm) |
There was a problem hiding this comment.
The idea was to add some kind of support for any node version manager. NVM is just one of them but there is also NVS, FNM and other
| npm install --global yo @microsoft/generator-sharepoint gulp-cli | ||
| ``` | ||
|
|
||
| > ℹ️ **Gulp vs Heft**: SPFx v1.22+ uses Heft by default (no global `gulp-cli` needed). However, keeping `gulp-cli` installed globally is harmless and covers legacy projects. |
There was a problem hiding this comment.
This suggestion is wrong. There is no need to keep gulp-cli for newer versions of SPFx
| ### Install missing global dependencies | ||
|
|
||
| ```shell | ||
| npm install --global yo @microsoft/generator-sharepoint gulp-cli |
There was a problem hiding this comment.
This command is wrong for newere versions of SPFx which primary use Heft
| | Package | Latest | Notes | | ||
| |---|---|---| | ||
| | **Yeoman** (`yo`) | v5.x | Project scaffolding | | ||
| | **`@microsoft/generator-sharepoint`** | v1.23.x | SPFx project generator | | ||
| | **Gulp CLI** (`gulp-cli`) | v3.x | Required for SPFx ≤ v1.21.1 | | ||
| | **CLI for Microsoft 365** (`@pnp/cli-microsoft365`) | latest | Recommended for upgrades and tenant operations | |
There was a problem hiding this comment.
keeping table with latest makes very little sense as it will get outdated fast. Like SPFx is already 1.24.2 beta.
| 1. **Install Node.js** — guide user to install manually (v20 or v22 for latest SPFx) | ||
| 2. **Install nvm** — confirm with user, then: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash` | ||
| 3. **Install Node via nvm:** `nvm install 20 && nvm alias default 20` |
There was a problem hiding this comment.
isn't this like misleading? Why install node in 1st step and then in 3rd step install node again using nvm?
| 4. **Install global tools:** `npm install --global yo @microsoft/generator-sharepoint` | ||
| 5. **Install Git** — guide user to [git-scm.com](https://git-scm.com/) if not present | ||
| 6. **Install VS Code** (optional) — guide user to [code.visualstudio.com](https://code.visualstudio.com/) | ||
| 7. **Validate:** run `node --version && npm --version && yo --version` to confirm |
There was a problem hiding this comment.
It would be best to suggest using m365 doctor command for validation since CLI for M365 is already a 'dependency' of those SPFx skills in other references
2 participants
Closes #2
What this adds
A new
setup.mdreference for thespfxskill that guides developers through:spfx doctorspfx doctorquick check + manual checklist.yo-rc.json/package.jsonUpdated SKILL.md
setup.mdto the intent router (listed first — check prerequisites before creating)argument-hintChanges