The SharePoint Framework (SPFx)

Analogy categoryAnalogies

What Is the SharePoint Framework?

The SharePoint Framework (SPFx) is Microsoft's open-source, client-side development model for building components — web parts and extensions — that run directly inside the rendering pipeline of a SharePoint Online page. Unlike the older SharePoint-hosted and provider-hosted add-in models, which loaded content in isolated iframes, SPFx components execute in the context of the current page and user, using standard web tooling: TypeScript, npm, webpack, and gulp. Components can be built with React, Vue, Handlebars, or plain TypeScript, since SPFx itself does not mandate a UI framework.

🏏

Cricket analogy: Just as the DRS replaced purely on-field umpiring decisions with a more integrated, technology-driven review process, SPFx replaced the old SharePoint-hosted add-in model with a client-side framework that runs directly inside the page rendering pipeline.

Web Parts and the Component Model

Every SPFx web part extends BaseClientSideWebPart and implements a render() method that produces its markup. The component's manifest.json declares a unique GUID that SharePoint uses to identify the web part regardless of its display name, along with metadata like supported hosts and preconfigured entries. Configuration options exposed to end users — text fields, toggles, dropdowns — are defined through the property pane API, letting a site owner tune a web part's behavior without touching code.

🏏

Cricket analogy: The manifest.json GUID acts like a player's unique BCCI registration number issued to someone like Rohit Sharma, letting the SharePoint page load exactly the right component even if the display name changes.

Scaffolding a Project with Yeoman

New SPFx projects are created with the Yeoman generator, yo @microsoft/sharepoint, which prompts for the solution name, component type, and framework, then produces a working project with gulp as the task runner. gulp serve launches a local or hosted workbench for iterative testing, while webpack handles module bundling behind the scenes so multiple TypeScript files compile into a small number of production bundles.

🏏

Cricket analogy: Running yo @microsoft/sharepoint is like a franchise's pre-season nets session where all the standard training drills — fitness, catching, throwing — are set up automatically before players even arrive.

typescript

// Scaffold: yo @microsoft/sharepoint

import { BaseClientSideWebPart } from '@microsoft/sp-webpart-base';
import * as React from 'react';
import * as ReactDom from 'react-dom';

export interface IHelloWorldWebPartProps {
  description: string;
}

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    const element = React.createElement('div', { className: 'helloWorld' },
      `Hello, ${this.context.pageContext.user.displayName}!`
    );
    ReactDom.render(element, this.domElement);
  }
}

// Local iteration: gulp serve
// Production build: gulp bundle --ship && gulp package-solution --ship

Extensions: Field Customizers, Command Sets, Application Customizers

SPFx extensions modify existing SharePoint UI rather than being placed on a page. Field customizers change how a single list column renders (e.g., a progress bar instead of a plain number). Command sets add custom buttons or menu items to the command bar or a list item's context menu. Application customizers inject content into predefined page placeholders, such as a top banner or bottom footer region, and apply consistently across every page they're deployed to.

🏏

Cricket analogy: Field customizers are like a stadium's giant screen replay overlay that changes how a boundary rope looks without touching the actual pitch, just as they change how a list column renders without altering the data.

SPFx version compatibility is tied to the SharePoint Online service, not a specific tenant release cycle — Microsoft ships new SPFx versions roughly twice a year, and a package built against a recent SPFx version generally still runs because Online is evergreen. On-premises SharePoint Server (Subscription Edition), however, only supports specific pinned SPFx versions, so always check the target environment before choosing a generator version.

Packaging and Deploying to the App Catalog

Production solutions are built with gulp bundle --ship, which minifies and prepares assets, followed by gulp package-solution --ship, which produces a single .sppkg package. That package is uploaded to the tenant app catalog (for tenant-wide availability) or a site collection app catalog (for scoped availability), and static assets are typically hosted on a CDN referenced by the manifest for performance and caching.

🏏

Cricket analogy: Publishing the .sppkg to the tenant app catalog is like registering a new player with the ICC before they can appear in an international match — until they're listed, the officials won't let them onto the field.

Any web part or extension that calls the Microsoft Graph API through AadHttpClient requires the requested API permission to be explicitly approved by a SharePoint administrator on the 'API access' page of the SharePoint admin center. Until approved, calls fail with a 401/403 even though the code and manifest are correct, and this approval step is easy to forget during a first deployment.

SPFx is Microsoft's open-source, client-side framework for building web parts and extensions that run natively inside SharePoint Online pages.
Web parts extend BaseClientSideWebPart and are uniquely identified by a GUID in manifest.json.
Yeoman (yo @microsoft/sharepoint) scaffolds new projects; gulp drives build, serve, bundle, and package tasks.
Extensions come in three types: field customizers, command sets, and application customizers.
Solutions are packaged as a single .sppkg file and deployed through the tenant or site collection app catalog.
Static assets should be hosted on a CDN via gulp bundle --ship for production performance.
Graph API permissions requested by a component must be approved in the SharePoint admin center before calls succeed.