spfx-implementation-docs

Generates the team's Implementation Guides for SPFx projects: one fixed, twelve-section document per project covering SharePoint list provisioning, Dataverse tables, Power Automate flow build-out, package deployment, web part setup, and a verification checklist — written so someone with no SharePoint or Power Automate experience can follow it.

Nobody writes the Markdown. Each project keeps a validated docs/implementation/implementation.json; this tool renders IMPLEMENTATION.md from it. Same renderer for every project ⇒ identical format, always. The full standard and quality bar live in IMPLEMENTATION-DOCS.md.

Setup (once)

git clone <this-repo-url>       # anywhere; a sibling of your SPFx projects is convenient
cd spfx-implementation-docs
npm install                     # one dependency (ajv, for schema validation)

Optional: npm link makes the command available everywhere as spfx-docs.

Use

# 1. scaffold the source file in your project (first time only)
node bin/spfx-docs.mjs --app ..\my-project-spfx --init

# 2. fill in docs/implementation/implementation.json (see the schema + the reference projects)

# 3. validate + render the guide
node bin/spfx-docs.mjs --app ..\my-project-spfx

# CI / pre-commit: validate only
node bin/spfx-docs.mjs --app ..\my-project-spfx --check

Commit implementation.json and the rendered IMPLEMENTATION.md together.

Central publishing

If a folder named _implementation-docs exists at or above your project folder (ours lives at C:\Repos\ExecutiveOffice\_implementation-docs), every successful render also copies the guide there as <project>.md and regenerates the folder's index README — one easy-to-find place with every project's guide. --no-publish skips it; --publish-dir <dir> forces a specific folder.

What the generator does for you

• Novice click-paths from raw data. You record a column as { "internalName": "OrgStatus", "type": "Choice", "choices": ["Filled", "Acting"] } — the guide gets the exact SharePoint steps, including creating the column under its internal name first and renaming afterwards (SharePoint locks internal names at creation).
• Flows someone can build literally. One JSON step per designer action renders as "Action: SharePoint → Get items" plus a field-by-field configuration table, connections, error-handling wiring, and a test procedure.
• Auto-extracted facts. Deployment (solution name/id/version, CDN base path, tenant deployment sequence and guardrails) and web-part property tables come straight from the project's config/package-solution.json, config/write-manifests.json, and web part manifests.
• Loud validation. Schema errors print with exact JSON paths and allowed values before anything renders.

Reference implementations

In the Executive Office workspace: org-chart-spfx/docs/implementation/ (list-centric) and subscription-service-spfx/docs/implementation/ (two lists + two fully spec'd flows). Open the implementation.json next to its rendered IMPLEMENTATION.md to see how source becomes deliverable.

Asking an agent to do it

Paste the "Build an implementation plan" prompt from IMPLEMENTATION-DOCS.md into Claude (or any agent) — it extracts real column internal names and flow contracts from the project's code, fills implementation.json, and renders.