EXPLAINER

How to Build an SPFx Web Part

Build an SPFx web part by scaffolding a React and TypeScript project with the SharePoint generator, coding against the web part context, serving the workbench, then packaging an .sppkg for the app catalog.

Short answer: To build an SPFx web part: match Node to your SPFx version, scaffold with the SharePoint Yeoman generator (React + TypeScript), implement the component, run it on the workbench (heft start on SPFx v1.22+, gulp serve on older toolchains), then ship an .sppkg to the app catalog. Background: what SPFx is.

What it is

Building an SPFx web part means creating a SharePoint Framework project whose output is a component an author can drop on a modern SharePoint page. The part is TypeScript, usually React, bundled by the SPFx toolchain and installed from a .sppkg package. This page is the practical sequence. For what the framework is, and for the direct answers "Does SPFx use React?" and "Is SPFx TypeScript?", read SharePoint Framework (SPFx).

Why and when it is used

Follow this path when you are ready to put custom UI on a SharePoint page: a filtered view of a list, a small form, or a card that calls Microsoft Graph. Skip it for a one-off edit a built-in web part already covers. Also skip it if you do not have a tenant where you can upload a package; the local workbench is only half the story.

How it works

The generator writes a solution with config/, src/webparts/<name>/, a manifest, localisation strings and a React component. The web part class wires the property pane and renders the React element, passing this.context and the current properties. SharePoint loads that class when the page renders the part. During development the workbench loads your bundle from localhost. In production SharePoint loads the bundle from the app catalog's deployed assets.

A minimal data call uses this.context.spHttpClient.get(listUrl, SPHttpClient.configurations.v1) or the Graph client. You parse JSON, keep it in React state, and render. Errors from permissions or throttling should show in the part, not only in the console.

Technologies and dependencies

You need a supported Node.js for that SPFx release, npm, the Yeoman SharePoint generator (@microsoft/generator-sharepoint), the build CLI for your toolchain (Heft — @rushstack/heft — for SPFx v1.22+; Gulp CLI for v1.0–v1.21.1), a Microsoft 365 tenant with an app catalog, and a code editor. React and TypeScript come in as project dependencies when you pick the React template. Fluent UI is optional but matches Microsoft 365 visuals. If the part calls Graph, an admin must approve the requested permissions. Your own developer certificate is required for HTTPS on the local workbench.

How to get started

  1. Check the SPFx version you will use and install a Node.js release it supports. Version mismatch is the most common first-day failure.
  2. Install tooling. For SPFx v1.22+ (Heft toolchain): npm install @rushstack/heft yo @microsoft/generator-sharepoint --global. For v1.21.1 and earlier, including SharePoint Server on-premises, follow the legacy gulp-based guide (npm install -g yo gulp-cli @microsoft/generator-sharepoint). Pin a generator version if your team standardises one.
  3. Create a folder and run yo @microsoft/sharepoint. Choose SharePoint Online (or the latest target), a WebPart, a name, and the React framework.
  4. Trust the developer certificate: heft trust-dev-cert on SPFx v1.22+ (after npm install), gulp trust-dev-cert on the legacy toolchain.
  5. Run heft start (or gulp serve on the legacy toolchain). Open the hosted workbench URL the console prints. Add your web part to the page.
  6. Edit src/webparts/<name>/components/<Name>.tsx. Start by rendering the site title from context so you know the part is wired. Then add one real behaviour, such as reading the titles of items in a list on the current web.
  7. Define properties in the manifest and property pane only for values an author should change (list title, row count). Do not put secrets there.
  8. When it works on the workbench, add the same part to a real modern page in your dev site.
  9. Package: heft build --production then heft package-solution --production on SPFx v1.22+ (legacy toolchain: gulp bundle --ship and gulp package-solution --ship). Upload the .sppkg from sharepoint/solution to the tenant app catalog. Deploy it. If the package requests API permissions, approve them in the SharePoint admin API access page.
  10. Add the web part on a page as a user who is not you. If it fails, the bug is usually permissions, not React.

Commit package-lock.json. Write the Node and SPFx versions in the README. The next build should be repeatable.

Cautions and trade-offs

Do not upgrade Node globally "to latest" on a machine that builds SPFx; keep a version manager. Do not ship a debug build that still loads assets from localhost (the heft start / gulp serve workbench setup). Do not store API keys in the bundle; anyone can read it. Property bag values are not secret either.

Test the packaged solution, not only the workbench. The workbench does not prove app-catalog deployment, CDN paths or admin consent. Respect list view thresholds: requesting every row with no filter will fail in real libraries. Handle loading and error states so a slow Graph call does not look like a blank web part. And keep the solution small. If you are building a full application with routing, accounts and its own database, SPFx should be a thin host or you should build that application elsewhere and link to it.