SPFx Foundations: Scaffold, Project Anatomy & the Dev Loop

Lesson 3: SPFx Foundations — Scaffold, Project Anatomy & the Dev Loop

SharePoint Framework (SPFx) is the modern model for building SharePoint customizations: your components are ordinary web assets (TypeScript compiled to JS bundles) that SharePoint's client-side runtime loads inside modern pages. No server code, no farm installs — just a package your app catalog serves. SPFx also lets one codebase target SharePoint, Microsoft Teams tabs/personal apps, and Outlook add-ins, because the components are host-agnostic web parts underneath.

What you can build with SPFx

ComponentWhat it does
Client-side web partA self-contained widget authors drag onto any page. The bread-and-butter of this course.
Application customizerCode that runs on every page of a site — injects headers/footers/scripts.
Field customizerCustom rendering for a list column's cells.
List view command setCustom buttons in a list's toolbar / item context menu.
Library componentShared code (e.g. a common data layer) other solutions consume.

The toolchain

SPFx development runs on Node.js with a Microsoft-maintained build toolchain (webpack underneath). One important version note: SPFx v1.22+ moved from the classic Gulp-based toolchain to a Heft-based one (Rushstack). New scaffolds use Heft; older projects (v1.0–v1.21.1) and most legacy samples still use Gulp. Commands differ slightly, and this course shows the current Heft form with the Gulp equivalent alongside.

# install the global scaffolding tool (once)
npm install -g yo @microsoft/generator-sharepoint

# scaffold a new solution in a fresh folder
yo @microsoft/sharepoint

The generator asks a few questions: your solution name, which SharePoint environment (Online, or an on-premises version if relevant), the framework you want (React or no JavaScript framework — both are first-class; start with "no framework" to learn the mechanics), and which component type to scaffold (a web part is the default). It then produces a complete, runnable project.

Node version discipline: SPFx pins each release to a specific Node.js LTS line (the support table in the docs tells you which). If you work on several SPFx projects, manage Node versions with nvm (macOS/Linux) or nvm-windows so each repo's .nvmrc/engines gets the right runtime. Wrong Node is the #1 cause of mysterious gulp failures.

Anatomy of a generated project

PathPurpose
config/package-solution.jsonThe identity of your deployable solution: name, GUID, version, tenant-wide flags. This becomes the .sppkg.
config/serve.jsonDev-server settings — which workbench to open, port (default 4321).
config/write-manifests.json, copy-assets.json, etc.Build plumbing: asset copying and manifest emission.
src/index.tsEntry point that registers every component in the bundle.
src/webparts/<name>/<Name>WebPart.tsThe web part class — where you render.
src/webparts/<name>/<Name>WebPart.manifest.jsonComponent manifest: id, title, icon, default properties, supported hosts.
src/webparts/<name>/loc/*.jsLocalized UI strings (en-us by default).
src/webparts/<name>/<Name>WebPart.module.scssCSS module styles scoped to your component.
gulpfile.js (legacy) / Heft config, package.json, tsconfig.jsonBuild orchestration, dependencies, TypeScript config.

The dev loop: heft start + the workbench

During development you never upload anything. You run a local build server and preview against SharePoint's workbench:

heft start          # legacy gulp-based projects (SPFx v1.0-1.21.1): gulp serve
  • Local workbench (default): opens the workbench on https://localhost:4321 — your component runs isolated from a real site. The first run handles the local HTTPS certificate setup for you.
  • Hosted workbench: better for real data. Open https://<your-tenant>.sharepoint.com/_layouts/15/workbench.aspx and add ?debugManifestsFile=https://localhost:4321/temp/manifests.js so the page loads your locally-served component. Your web part then renders against the real site, with real lists and permissions.

Save a file → the dev server recompiles → refresh the workbench. When you're happy, stop and produce the shippable package (Lesson 7):

heft build --clean --production
heft package-solution --production
# legacy gulp-based projects instead run:
#   gulp clean && gulp bundle --ship && gulp package-solution --ship

That last command emits sharepoint/solution/<name>.sppkg — the file everything downstream deploys. (Both toolsets expose these through package.json scripts too, so npm run bundle -- --ship-style invocations appear in many repos and CI files.)

Pro tip: keep DevTools open during workbench sessions. SPFx logs component load/errors to the console, and a failed web part almost always explains itself there before you ever touch the package.

🧠 Knowledge Check

1. Which command scaffolds a new SPFx solution?

2. What does heft start do in a current SPFx project?

3. Where does the hosted workbench live, and what extra query parameter makes it load your local component?

Further Reading