SharePoint SPFx Development Guide

What Is SharePoint Framework (SPFx) and How Is It Used in 2026?

SharePoint Framework (SPFx) is the recommended development model for extending SharePoint Online with custom web parts, extensions, and Adaptive Card Extensions (ACEs) that run client-side in the browser. In our 25+ years managing enterprise SharePoint environments, we have seen SPFx mature from a basic web part framework into a comprehensive development platform that powers custom dashboards, data integrations, workflow interfaces, and AI-enhanced experiences across Fortune 500 companies.

SPFx is the only supported way to add custom code to modern SharePoint pages. Server-side code, sandbox solutions, and SharePoint Designer customizations are all deprecated. If your organization needs custom functionality beyond out-of-the-box web parts, SPFx is the path forward.

SPFx Architecture in 2026

Current Version and Capabilities

As of 2026, SPFx 1.20+ provides:

• React 18 support: Modern React with concurrent features and improved rendering performance
• Node.js 18+ toolchain: Updated build tools with faster compilation
• Adaptive Card Extensions (ACEs): Custom cards for Viva Connections dashboard
• Teams integration: SPFx web parts run natively in Microsoft Teams tabs
• Microsoft Graph integration: First-class support for calling Microsoft Graph APIs
• Domain-isolated web parts: Enhanced security through iframe isolation for web parts with elevated permissions
• Top Actions: Custom toolbar buttons for web parts

Project Structure

A well-organized SPFx project follows this structure:

The src directory contains web parts (one folder per web part), shared components, services (API abstraction layer), models (TypeScript interfaces), utilities (helper functions), and constants. The config directory holds SPFx-specific configurations, and the devops directory contains CI/CD pipeline definitions.

Every component should be typed with TypeScript interfaces. Every API call should go through a service layer. Every reusable UI element should be a shared component. This structure scales from small projects (1-2 web parts) to large projects (20+ web parts) without refactoring.

Setting Up an Enterprise SPFx Development Environment

Prerequisites

Ensure your development environment includes:

• Node.js 18 LTS (required for SPFx 1.20+)
• npm or pnpm (pnpm preferred for faster installs and disk efficiency)
• Yeoman and the SPFx generator
• TypeScript 5.x (included with SPFx)
• Visual Studio Code with recommended extensions (SPFx Snippets, ESLint, Prettier)
• A SharePoint Online developer tenant for testing

Project Scaffolding

Use the Yeoman generator to scaffold new projects. Select the React framework and TypeScript. After scaffolding, immediately configure:

ESLint and Prettier: Add ESLint with the TypeScript parser and Prettier for consistent code formatting. Configure rules that enforce your team's coding standards and add pre-commit hooks using Husky to prevent non-compliant code from being committed.

Unit testing: Add Jest and React Testing Library for component testing. Configure test coverage thresholds (80% minimum) and integrate coverage reporting into your CI pipeline.

Environment configuration: Create configuration files for development, staging, and production environments. Use SPFx property panes for user-configurable settings and environment variables for deployment-specific values (API endpoints, tenant URLs).

Web Part Development Patterns

Service Layer Pattern

Never call APIs directly from React components. Create service classes that encapsulate API calls and data transformation:

The service layer creates a clean separation between UI and data. Components call service methods without knowing the implementation details. When an API changes, you update the service layer without touching any components.

Context and Dependency Injection

Pass the SPFx web part context through React context rather than prop drilling. Create a custom context provider that exposes the SPFx context, Graph client, and service instances to all child components. This eliminates the need to pass context through multiple component layers.

State Management

For simple web parts, React's built-in useState and useContext are sufficient. For complex web parts with shared state across many components, consider:

• React Context + useReducer: Built-in, no dependencies, works well for medium complexity
• Zustand: Lightweight state management library, minimal boilerplate
• TanStack Query (React Query): Excellent for server state management (API data fetching, caching, and synchronization)

Avoid Redux for SPFx projects — it adds unnecessary complexity for the typical web part use case.

Error Boundaries

Implement React Error Boundaries to catch rendering errors gracefully. A web part that crashes should display a user-friendly error message, not a blank space or cryptic error. Log errors to an application monitoring service (Application Insights, Sentry) for developer visibility.

API Integration

Microsoft Graph

Use the SPFx-provided MSGraphClientV3 for Graph API calls. The client handles authentication automatically using the current user's context. Common Graph operations in SharePoint web parts:

• Fetching user profiles and organizational data
• Reading and writing Planner tasks
• Accessing Teams data (channels, messages)
• Querying SharePoint search results
• Managing calendar events

Request Graph API permissions in your SPFx solution manifest. Permissions must be approved by a tenant administrator before the web part can use them. Follow the principle of least privilege — request only the permissions your web part actually needs.

SharePoint REST API

For SharePoint-specific operations, use the SPHttpClient provided by SPFx. The REST API is ideal for:

• Reading and writing list items
• Managing document libraries
• Working with content types and metadata
• Site provisioning and configuration

External APIs

For external API calls, use the HttpClient class from SPFx or fetch with appropriate CORS handling. If the external API does not support CORS, use Azure Functions as a proxy. Store API keys and secrets in Azure Key Vault, not in your SPFx code.

Deployment and CI/CD

App Catalog

SPFx solutions are deployed to the SharePoint App Catalog — either the tenant-wide catalog (for organization-wide deployment) or site-level catalogs (for site-specific solutions). Tenant-wide deployment makes the web part available across all sites without site-level installation.

CI/CD Pipeline

Automate builds and deployments using Azure DevOps or GitHub Actions:

Build stage: Install dependencies, compile TypeScript, run unit tests, check code coverage, run ESLint, and package the .sppkg file.

Deploy to staging: Upload the .sppkg to a staging App Catalog, run integration tests, and validate web part functionality on a test site.

Deploy to production: After staging validation, upload to the production App Catalog. Use the --skipFeatureDeployment flag for tenant-wide deployment without requiring site-level activation.

Versioning Strategy

Follow semantic versioning (major.minor.patch) for your SPFx solutions. Increment the patch version for bug fixes, minor version for new features, and major version for breaking changes. Update the version in both package.json and the solution manifest to keep them in sync.

Performance Best Practices

Bundle Size

Keep your web part bundles small:

• Use dynamic imports (lazy loading) for features not needed on initial render
• Analyze bundle contents with webpack-bundle-analyzer
• Replace heavy dependencies with lighter alternatives (date-fns instead of moment.js, lodash-es with tree shaking instead of full lodash)
• Target under 100 KB gzipped for the main bundle

Rendering Performance

• Use React.memo for components that receive stable props
• Implement virtualization for long lists (react-window)
• Debounce search inputs and other frequent state updates
• Avoid inline function definitions in JSX (they create new references on every render)
• Profile with React DevTools and address components that re-render excessively

Data Fetching

• Cache API responses appropriately (5 minutes for user data, 1 hour for taxonomy data, 24 hours for configuration)
• Use TanStack Query for automatic caching, deduplication, and background refetching
• Implement pagination for large data sets rather than loading everything at once
• Use GraphQL batching when multiple Graph calls are needed

Loading Experience

• Show shimmer placeholders (from Fluent UI) while data loads
• Implement progressive loading — show the web part shell immediately, then populate data
• Pre-fetch data during the web part initialization phase before the first render

Security Best Practices

Permission Model

• Request minimum necessary API permissions in the solution manifest
• Use domain-isolated web parts for elevated permissions (they run in an iframe sandbox)
• Never hardcode secrets, API keys, or tenant-specific URLs in code
• Validate all user inputs to prevent XSS and injection attacks

Code Review Standards

Establish mandatory code review requirements for all SPFx code:

• No direct DOM manipulation (use React's virtual DOM)
• No eval() or innerHTML usage
• All external data must be sanitized before rendering
• API calls must handle errors gracefully
• No console.log statements in production code

Governance for Custom Solutions

Solution Catalog Management

Maintain an inventory of all deployed SPFx solutions:

• Solution name and version
• Business owner and developer contact
• Sites where the solution is deployed
• API permissions granted
• Last update date
• Next review date

Review this inventory quarterly and remove solutions that are no longer maintained or used.

Development Standards Documentation

Create and maintain a development standards guide that covers:

• Coding conventions (naming, file structure, TypeScript patterns)
• Testing requirements (minimum coverage, test types)
• API integration patterns (service layer, error handling, caching)
• Deployment procedures (CI/CD, approval gates, rollback plans)
• Performance budgets (bundle size limits, load time targets)

Our [SharePoint consulting services](/services/sharepoint-consulting) include SPFx development for enterprises that need custom solutions built to production standards. Our development team follows all the practices outlined in this guide and delivers solutions with full documentation, testing, and CI/CD pipelines.

For organizations that need ongoing SPFx development support, our [managed services](/services/sharepoint-support) include monthly development hours for custom web part creation, maintenance, and upgrades. If you are [migrating to SharePoint Online](/services/sharepoint-migration) and need to rebuild legacy customizations in SPFx, our migration team includes experienced SPFx developers. [Contact us](/contact) to discuss your development needs.

Frequently Asked Questions

Do I need to know React to develop SPFx web parts?

React is the recommended and most widely used framework for SPFx, but it is not the only option. You can also build web parts with no framework (vanilla JavaScript/TypeScript). However, for enterprise web parts with complex UI, React provides the best developer experience, largest community, and most available resources. Invest in React knowledge for your SPFx development team.

Can SPFx web parts run in Microsoft Teams?

Yes. SPFx web parts can be configured to run as Teams personal apps, Teams tabs, and Teams meeting extensions. The same codebase serves both SharePoint and Teams with platform-aware rendering. This eliminates the need to maintain separate solutions for each platform.

How do I debug SPFx web parts?

Use the SharePoint Workbench (local or hosted) for development-time testing. Set breakpoints in Visual Studio Code and use the "Attach to Chrome" debug configuration. For production debugging, use browser developer tools and Application Insights telemetry. Always include sufficient logging in your code for production issue diagnosis.

What is the difference between web parts and extensions?

Web parts are placed on SharePoint pages by editors and render in a defined area. Extensions modify the page globally — Application Customizers add headers/footers, Field Customizers change how list columns render, and Command Sets add buttons to list toolbars. Use web parts for content display and interaction; use extensions for global behavior modification.

How do I handle authentication for external APIs in SPFx?

Use AadHttpClient for APIs secured by Azure AD. Register the external API as an Azure AD app registration, configure the required permissions in your SPFx solution manifest, and use AadHttpClient to make authenticated calls. For non-Azure AD APIs, use Azure Functions as an intermediary that handles authentication.

Can I use npm packages in SPFx?

Yes, with caution. SPFx projects are standard Node.js projects and support npm packages. However, every package increases bundle size. Evaluate packages carefully — check bundle size impact, maintenance status, and security vulnerabilities. Prefer packages that support tree shaking (ES modules) over those that do not.

How do I upgrade an existing SPFx solution to a newer version?

Use the Office365 CLI or PnP CLI to run the SPFx upgrade command, which identifies required changes between your current version and the target version. Apply changes incrementally, test thoroughly after each upgrade step, and update your CI/CD pipeline to use the new Node.js and toolchain versions. Never skip major versions — upgrade through each major version sequentially.

What is an Adaptive Card Extension (ACE)?

ACEs are lightweight, card-based UI components designed for the Viva Connections dashboard. They provide quick information and actions without full-page navigation. ACEs are built using the SPFx framework but render as cards rather than page-embedded web parts. They are ideal for approval actions, status displays, quick data entry, and notification summaries.