Building Your First SPFx Web Part: A Complete Step-by-Step Guide

Scaffolding Your First Web Part

Create a new directory for your project and run the Yeoman generator. The interactive wizard will ask you a series of questions — your answers define the project name, component type (web part vs. extension), framework (React, No framework, or Knockout), and target SharePoint version.

# Create and navigate to your project folder
mkdir hello-world-webpart
cd hello-world-webpart

# Run the Yeoman generator
yo @microsoft/sharepoint

# Answer the prompts:
# Solution name: hello-world-webpart
# Target: SharePoint Online only (latest)
# Component type: WebPart
# Web part name: HelloWorld
# Framework: React

# Once scaffolded, install dependencies
npm install

# Start the local workbench
gulp serve

After gulp serve launches, open https://localhost:4321/temp/workbench.html in your browser. Accept the self-signed certificate warning on first run. You'll see the SharePoint Workbench — a sandboxed page where you can add and test your web part without deploying to a real SharePoint site. This inner loop development workflow is what makes SPFx productive once you're set up.

Understanding the File Structure

The scaffold generates a well-organised project with a clear separation of concerns. Understanding where things live before you start editing is essential — too many developers get lost because they try to modify the wrong file.

• src/webparts/helloWorld/HelloWorldWebPart.ts — The web part entry point. This class extends BaseClientSideWebPart and is responsible for rendering, property pane configuration, and lifecycle hooks.
• src/webparts/helloWorld/components/HelloWorld.tsx — The React component. This is where your UI lives. The web part passes data down as props.
• src/webparts/helloWorld/HelloWorldWebPart.manifest.json — Metadata about your web part: ID, title, description, and the supported hosts (SharePoint, Teams, etc.).
• config/package-solution.json — Defines the solution package. This is where you add API permission requests for Microsoft Graph.
• config/serve.json — Configuration for gulp serve, including the initial page to load and any query string parameters.

The config/ folder deserves special attention. Files like deploy-azure-storage.json, package-solution.json, and write-manifests.json control the production build and deployment pipeline. Don't ignore them — misconfigurations here are the second-most-common source of deployment failures, after Node version mismatches.

Building the React Component

The generated HelloWorld.tsx is a class component by default. Modern React development prefers functional components with hooks, and SPFx supports them fully. Here's a cleaned-up functional component that accepts props typed with an interface:

import * as React from 'react';
import { useState, useEffect } from 'react';
import { IHelloWorldProps } from './IHelloWorldProps';

const HelloWorld: React.FC<IHelloWorldProps> = ({ description, currentUser }) => {
  const [greeting, setGreeting] = useState<string>('');

  useEffect(() => {
    const hour = new Date().getHours();
    if (hour < 12) setGreeting('Good morning');
    else if (hour < 17) setGreeting('Good afternoon');
    else setGreeting('Good evening');
  }, []);

  return (
    <div className="helloWorld">
      <h2>{greeting}, {currentUser}</h2>
      <p>{description}</p>
    </div>
  );
};

export default HelloWorld;

The corresponding props interface lives in a separate file at src/webparts/helloWorld/components/IHelloWorldProps.ts. Separating interfaces keeps your components clean and makes it obvious which data each component depends on. When you start building larger web parts with multiple nested components, this discipline pays dividends.

Calling Microsoft Graph API

One of the greatest strengths of SPFx is direct, authenticated access to the Microsoft Graph API without any backend service. The framework provides the MSGraphClientV3 class which wraps the @microsoft/microsoft-graph-client library and handles token acquisition transparently using the logged-in user's session.

To use the Graph API, you first need to declare the permissions your web part requires in config/package-solution.json. Once deployed, a SharePoint admin approves these permissions in the SharePoint Admin Centre under API Access.

import { MSGraphClientV3 } from '@microsoft/sp-http';

// Inside your web part's render() method or an async helper:
private async getCurrentUser(): Promise<string> {
  const client: MSGraphClientV3 = await this.context.msGraphClientFactory
    .getClient('3');

  const response = await client
    .api('/me')
    .select('displayName,mail')
    .get();

  return response.displayName;
}

The getClient('3') call specifies MSGraphClientV3 — always use version 3 in new projects as versions 1 and 2 are deprecated. The fluent API then lets you chain .api(), .select(), .filter(), .top(), and .get() calls in a readable style. Error handling should wrap the entire call in a try/catch since the Graph API returns HTTP errors as thrown exceptions through the SDK.

Deploying to SharePoint App Catalog

When your web part is ready for testing on a real SharePoint site, you need to package and deploy it. The process has two steps: build a production bundle, then upload the resulting .sppkg file to the App Catalog.

# Bundle for production (minified, no source maps)
gulp bundle --ship

# Create the .sppkg package
gulp package-solution --ship

# The output file will be at:
# sharepoint/solution/hello-world-webpart.sppkg

Navigate to your SharePoint Admin Centre, go to More features → Apps → Open, and upload the .sppkg file. If your web part requests API permissions, a yellow banner will appear prompting an administrator to approve them under API Access. Approvals are tenant-wide — once granted, all web parts in the tenant can use that permission scope.

After approval, go to any modern SharePoint site, click the gear icon, choose Add an app, find your web part package, and install it. Then edit any modern page and you'll find your web part in the toolbox under your solution name.

Troubleshooting Common Errors

Even with a clean setup, you'll encounter errors. Here are the ones that consume the most developer time and their reliable fixes.

• "Cannot find module '@microsoft/sp-core-library'" — Run npm install again. This appears after a botched install or switching branches with different dependency trees.
• Certificate errors on localhost:4321 — Run gulp trust-dev-cert once to install the development certificate into your OS trust store. Restart the browser after.
• Web part doesn't appear in the toolbox after deployment — Check that the solution is deployed and the app is installed on the site collection. These are two separate steps. Also verify the manifest ID in HelloWorldWebPart.manifest.json is unique and hasn't been accidentally duplicated from another solution.
• Graph API returns 403 Forbidden — The API permission hasn't been approved in SharePoint Admin Centre → API Access. The web part will silently fail until an admin grants the request.
• "gulp serve" throws EADDRINUSE — Port 4321 is already in use by another gulp serve process. Kill it with npx kill-port 4321 on Windows or lsof -ti:4321 | xargs kill on Mac.