verify-sample-pr-build

name	verify-sample-pr-build
description	Verify that the SPFx ACE sample(s) touched by a pull request in this repo build successfully before merging. Use when: reviewing a PR, "verify PR build", "check if this PR builds", "test sample before merging", validating a submitted sample or an SPFx version upgrade in samples/**. Checks out the PR branch locally, installs dependencies only in the affected sample folder(s), runs the sample-specific build command (gulp or Heft toolchain), reports pass/fail, then cleans up.
argument-hint	<PR number or URL>

Verify Sample PR Build

Each sample under samples/<SampleName>/ in this repo (pnp/sp-dev-fx-aces) is a fully standalone SPFx project with its own package.json / package-lock.json. There is no root-level package.json. A PR almost always touches exactly one sample folder — dependencies only need to be installed there, never at the repo root.

When to Use

• Before merging a PR that adds or modifies a sample
• Verifying an SPFx version upgrade (e.g. Gulp → Heft toolchain migration)
• Spot-checking a contributor's submission builds cleanly

Known Tool Quirk: Verify Your Working Directory

The terminal tool can silently "simplify" a chained cd <path> && <command> and drop the cd, leaving a stale cwd from a previous task/session in place. This has caused commands to silently run against the wrong sample folder.

Mitigation — apply both:

1. Prefer absolute paths over cd. Use npm --prefix /abs/path/to/samples/<Name> install and npm --prefix /abs/path/to/samples/<Name> run build instead of cd ... && npm .... This works regardless of the shell's persisted cwd.
2. If you must cd, issue it as its own standalone command, then immediately run pwd as a separate call and confirm it matches the expected sample path before running anything else. Never assume a chained cd took effect.

Procedure

1. Identify the affected sample folder(s)

Get the PR number/URL from the user, then find which samples/<Name>/ directories it touches:

gh pr view <PR_NUMBER> --repo pnp/sp-dev-fx-aces --json files --jq '.files[].path' \
  | grep -oE '^samples/[^/]+' | sort -u

Or use the helper: get-changed-samples.sh

If more than one sample folder is touched, repeat steps 2-5 for each.

2. Check out the PR branch locally

This is local-only and fully reversible (does not touch remote/origin):

gh pr checkout <PR_NUMBER> --repo pnp/sp-dev-fx-aces

3. Determine the required Node.js version

SPFx version requirements vary a lot across samples in this repo (some are years old). Check, in order of preference, inside the affected sample folder:

1. package.json → "engines": { "node": "..." }
2. .yo-rc.json → "@microsoft/generator-sharepoint" > "nodeVersion"
3. If absent, infer roughly from the .yo-rc.json "version" (SPFx version):
   • SPFx 1.21+ → Node 22.x (Heft toolchain, useGulp: false)
   • SPFx 1.17–1.20 → Node 18.x or 22.x
   • SPFx 1.15–1.16 → Node 16.x or 18.x
   • SPFx < 1.15 → Node 12.x/14.x

Switch to that version with nvm (already available in this container):

nvm install <version> && nvm use <version>

4. Install dependencies (sample folder only)

Use an absolute path with npm --prefix instead of cd (see cwd-safety note above):

npm --prefix <abs-path>/samples/<SampleName> install

5. Determine the toolchain and build

Check .yo-rc.json for "useGulp": false (Heft) vs absent/true (Gulp), or just inspect package.json scripts / presence of gulpfile.js:

• Heft toolchain (SPFx 1.21+, no gulpfile.js, has @rushstack/heft dep):

  npm --prefix <abs-path>/samples/<SampleName> run build
  

  (typically runs heft test --clean --production && heft package-solution --production)

• Gulp toolchain (older samples, has gulpfile.js):

  (cd <abs-path>/samples/<SampleName> && npx gulp bundle --ship && npx gulp package-solution --ship)
  

  Run as a single subshell command so the cd can't be dropped or leak into later commands. (npm run build alone may only run gulp bundle without --ship; prefer the exact commands listed in the sample's own README.md "Minimal Path to Awesome" section — it is the authoritative source per sample.)

Watch the output for: TypeScript compile errors, ESLint errors, Webpack failures, and packaging errors. A successful run ends with the .sppkg written under sharepoint/solution/.

6. Report result

Summarize per sample: pass/fail, and paste/summarize any errors encountered. Do not push, comment on, or merge the PR yourself — only report findings.

7. Clean up

Always clean up after verification, whether it passed or failed.

Remove build artifacts using an absolute path (no cd required): cleanup-sample-build.sh

./.github/skills/verify-sample-pr-build/scripts/cleanup-sample-build.sh <abs-path>/samples/<SampleName>

Then return to the repo root and switch branches as standalone commands, verifying with pwd before continuing:

cd <abs-repo-root>
pwd   # confirm it printed the repo root before continuing
git checkout main
git branch -D <pr-branch-name>

Finally, verify with git status --short that the sample folder has no leftover untracked build artifacts (e.g. toolchain-specific output directories the cleanup script doesn't yet know about). If something remains, remove it manually and consider adding it to cleanup-sample-build.sh for next time.

Notes

• Never run this against main/origin destructively — gh pr checkout and git branch -D only affect the local clone.
• npm install inside a sample can print deprecation warnings and moderate/critical audit warnings from transitive deps — this is normal for older SPFx samples and not a build failure signal.
• Always double-check the working directory before running install/build/cleanup commands — see the cwd-safety note above. Prefer absolute paths and npm --prefix over relying on cd persisting across tool calls.