Build Your First SPFx Web Part: Hello World Guide (2026)

What Is SharePoint Framework (SPFx)?

SharePoint Framework is Microsoft's modern development model for building extensible applications that run securely within SharePoint Online, Microsoft Teams, and Viva Connections. Unlike legacy SharePoint Solutions, SPFx web parts are lightweight, maintainable, and built with contemporary web technologies like React, TypeScript, and Webpack.

SPFx web parts execute in a sandboxed browser context (the isolated web part domain), which means you can build feature-rich components without server-side code or elevated permissions. This guide walks you through building your first web part using the current best-practice toolchain: SPFx CLI with Heft.

Prerequisites

Before you start, ensure you have:

• Node.js 20+ LTS (v20.11 or later; NOT v18, which has reached end-of-life)

• SPFx CLI (the modern scaffolding tool; replaces Yeoman)

• VS Code with SharePoint Framework Tools extension

• A SharePoint Online tenant (or developer site) with App Catalog enabled

• Basic familiarity with TypeScript and React

Verify your Node.js version:

node --version

Install SPFx CLI

The SPFx CLI is the recommended way to scaffold new projects. Install it globally:

npm install -g @microsoft/spfx

Verify installation:

spfx --version

Scaffold Your Project Using SPFx CLI

The SPFx CLI simplifies project setup with interactive prompts. Run:

spfx init

You'll be guided through:

• Package name — hello-world-webpart

• Framework — Select React

• Component name — HelloWorld

• Web part description — My first SPFx web part

The CLI creates a complete project structure with modern tooling (Heft, Webpack, ESLint) already configured.

Project Structure Overview

Here's what SPFx scaffolds for you:

Folder	Purpose
src/	TypeScript/React source files
src/webparts/HelloWorld/	Your web part component and manifest
lib/	Compiled JavaScript (generated on build)
sharepoint/	Solution package configuration
config/	Build configuration (Heft, Webpack)
node_modules/	Dependencies
package.json	Project metadata and scripts

The key files you'll edit are inside src/webparts/HelloWorld/:

• HelloWorldWebPart.ts — Main web part class (entry point)

• HelloWorld.tsx — React component (your UI)

• HelloWorldWebPart.manifest.json — Web part metadata (name, description, icon)

Install Dependencies

Navigate to your project and install:

cd hello-world-webpart
npm install

Run Locally with Heft

The modern SPFx stack uses Heft as the task runner. Start the development server:

heft run build

In another terminal:

npm run serve

This launches a local workbench at https://localhost:4321/workbench. You'll see your web part rendered in a test page, complete with hot reload on file changes.

Understanding the HelloWorld Web Part

Open src/webparts/HelloWorld/HelloWorld.tsx:

import * as React from 'react';
import styles from './HelloWorld.module.scss';
export interface IHelloWorldProps {
  title: string;
}
export const HelloWorld: React.FC<IHelloWorldProps> = (props) => {
  return (
    <div className={styles.container}>
      <h1>{props.title}</h1>
      <p>Welcome to your first SPFx web part!</p>
    </div>
  );
};

This is a simple React functional component. You can modify the JSX to build your UI.

Adding a Property Pane

The property pane lets users configure your web part without editing code. Open HelloWorldWebPart.ts and update the getPropertyPaneConfiguration() method:

protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
  return {
    pages: [
      {
        header: { description: 'Configure your web part' },
        groups: [
          {
            groupName: 'Settings',
            groupFields: [
              PropertyPaneTextField('title', {
                label: 'Web Part Title',
                value: this.properties.title,
                onPropertyPaneFieldChanged: this.onPropertyTitleChanged.bind(this),
              }),
            ],
          },
        ],
      },
    ],
  };
}
private onPropertyTitleChanged(value: string): void {
  this.properties.title = value;
}

Now users can edit the title property via the web part's settings panel.

Build and Bundle for Production

When you're ready to deploy, create an optimized bundle:

heft run build --production

This generates minified code in lib/. Next, package the solution:

npm run package

This creates a .sppkg file in the sharepoint/solution/ folder.

Deploy to SharePoint

• Upload to App Catalog: Go to your SharePoint tenant's App Catalog site (usually at https://[tenant]-admin.sharepoint.com/sites/appcatalog).

• Upload the .sppkg — Drag the .sppkg file into the Apps for SharePoint library.

• Trust the solution — Check "Make this solution available to all sites in the organization" if desired, then click Deploy.

• Add to a site — Go to any SharePoint site, open the site's App Catalog, find your web part app, and click Add It.

• Place the web part — Edit a modern page, click +, search for your web part, and add it.

Common Errors & Troubleshooting

Error	Cause	Fix
Node version not supported	Node.js < 20	Update: nvm install 20 or download from nodejs.org
Module not found: @microsoft/sp-core-library	Dependencies not installed	Run npm install
Certificate error on localhost	Dev cert issue	Run spfx trust-dev-cert
Web part not visible in workbench	Manifest misconfiguration	Verify HelloWorldWebPart.manifest.json has correct componentType: "WebPart"
Build fails with ESLint errors	Code style violations	Run npm run lint -- --fix to auto-correct
SPPKG deployment fails	App already exists with same ID	Change id in package-solution.json and rebuild

Legacy: Yeoman + Gulp (SPFx < 1.22)

If you're maintaining a project on an older version of SPFx (before 1.22), you may still be using the Yeoman + Gulp workflow. This is now deprecated but documented here for reference.

Installation:

npm install -g @microsoft/generator-sharepoint
npm install -g yo

Scaffold (legacy):

yo @microsoft/sharepoint

Run locally (legacy):

gulp serve

Build and package (legacy):

gulp bundle --ship
gulp package-solution --ship

Why upgrade? The SPFx CLI + Heft approach is faster, leaner, and better aligned with modern tooling. See our guide on migrating from Gulp to Heft and Webpack for details.

FAQ

Q: Can I use SPFx web parts in Microsoft Teams?
Yes. SPFx web parts can be deployed as Teams tabs. Your web part automatically works in Teams if it's registered in the solution manifest.

Q: How do I query SharePoint data from my web part?
Use the PnP JS library, which provides a fluent API for REST calls. Check out our guide on querying SharePoint lists with PnP JS.

Q: What's the difference between a web part and an Application Customizer?
Web parts are page-level components that users add to specific pages. Application Customizers run globally across your site and are great for injecting headers, footers, or site-wide navigation. Learn more in our Application Customizer guide.

Q: Can I build SPFx solutions without React?
Yes. The scaffolding tool offers options for React, Vue, or even plain TypeScript (no framework). Choose whichever fits your project needs.

Next Steps

Now that you have a working Hello World web part, here are some paths to level up your SPFx skills:

• Connect to real data — Learn how to query SharePoint lists and libraries using PnP JS inside your web part.

• Modernize your toolchain — Understand the architecture behind Heft and Webpack. See our guide on migrating from Gulp to Heft and Webpack for the latest approach.

• Build for Viva Connections — Extend your skills beyond web parts by creating Adaptive Card Extensions for Viva Connections.

• Add a global header or footer — Use an SPFx Application Customizer to inject headers and footers across your entire SharePoint site.

• Polish the UI — Once your web part renders, swap inline styles for Fluent UI v9 components to match the modern Microsoft 365 look.