spfx-best-practices

When to Use

Use this skill when:

• Creating or scaffolding new SPFx web parts, extensions (Application Customizers, Field Customizers, Command Sets) or libraries
• Reviewing or refactoring existing SPFx projects
• Extending existing solutions with new web parts or extensions while maintaining consistent patterns
• Answering questions about SPFx architecture, React, TypeScript, localization, styling (Sass), data access, authentication, Microsoft Graph, SharePoint APIs or tooling

Scope

Applies to:

• SPFx web parts, extensions and libraries
• React with TypeScript
• Localization (loc resources)
• Styling with Sass modules
• Data access (SharePoint REST, Microsoft Graph, Entra ID–secured APIs)
• SPFx toolchain (Heft / gulp / webpack)
• Modern SPFx development workflows

Technology Stack Constraints

When generating code, adhere to these specific library versions and standards unless instructed otherwise:

• Framework: SharePoint Framework (SPFx)
• UI Library: Fluent UI React (@fluentui/react)
• Data Access: PnPjs v4 (@pnp/sp, @pnp/graph, @pnp/logging)
• Language: TypeScript
• State Management: React Hooks
• Styling: CSS Modules (.module.scss) or Fluent UI Styling (mergeStyles)

Best Practices to Enforce

Project Structure & Architecture

• Use a feature-based or layered folder structure:

src/
common/
controls/
helpers/
hooks/
models/
services/
webparts/
extensions/

• Apply Separation of Concerns
• Keep UI, business logic and data access isolated
• Prefer reusable services over inline API logic

Toolchain & Build

• Target the latest supported SPFx version (e.g. 1.22.x+) if available.
  • Use Heft as the primary build orchestrator instead of gulp when starting new projects
• Avoid custom gulp hacks unless absolutely required
• Do not override toolchain defaults unless there is a documented, reproducible need
• Avoid unsupported patches and nonstandard build steps
• Keep configuration minimal and aligned with SPFx defaults
• Validate guidance against current SPFx release notes before shipping

TypeScript & Code Quality

• Enable strict TypeScript settings
• Avoid any; use interfaces, enums and generics
• Prefer async/await
• Keep utilities framework-agnostic where possible

React Best Practices

• Prefer functional components and React Hooks
• Keep components small and focused
• Extract logic into custom hooks or services
• Memoize expensive operations (useMemo, useCallback)
• Use Fluent UI for consistency and accessibility

Localization

• Use SPFx loc files for all user-facing strings
• Never hardcode display text
• Reference strings via strings.<Key>
• Ensure graceful fallback for missing translations
• Avoid string concatenation; use placeholders for plurals, dates and numbers

Styling (Sass)

• Use .module.scss files scoped to components
• Centralize shared variables, mixins and themes
• Avoid global CSS unless explicitly required
• Follow consistent naming conventions
• Controls: Use standard Fluent UI controls to match the M365 look and feel.
• Theming: strictly use ThemeProvider or the themeVariant object passed from the base context.
  • Rule: Never hardcode hex colors (e.g., #0078d4). Use semanticColors (e.g., theme.semanticColors.bodyText).
• Tokens: Prefer Fluent UI theme tokens over custom Sass variables for color and typography

Data Access Patterns

• Centralize data access in service classes
• Use PnPjs for most SharePoint operations if available
• Use SPHttpClient when:
  • Performing simple or low-level REST calls
  • Avoiding additional abstractions
• Handle errors, throttling and retries explicitly
• Prefer @pnp/sp and @pnp/graph for SharePoint and Graph REST interactions. Use native clients only when PnPjs is not available or when minimizing bundle size is a strictly stated priority.

Decision Matrix: PnPjs vs Native Clients

• Use @pnp/sp for SharePoint data access whenever possible
• Use @pnp/graph for Microsoft Graph when PnPjs is available
• Use MSGraphClientV3 only when PnPjs is not available or cannot be added
• Use SPHttpClient for minimal, low-level REST calls or bundle size constraints

Authentication & API Usage

• Use SPHttpClient or PnPjs for SharePoint REST APIs
• Use MSGraphClientV3 for Microsoft Graph access when PnPjs is not available
• Use AadTokenProvider for Entra ID–secured custom APIs
• Request least-privilege permissions
• Ensure Graph scopes align with webApiPermissionRequests and require admin consent
• Never store secrets in client-side code

Performance

• Lazy-load heavy components and libraries
• Use dynamic imports when appropriate
• Minimize bundle size
• Avoid unnecessary re-renders and excessive state
• Virtualize large lists and tables
• Avoid state updates in render loops

Security

• Sanitize and validate all user input
• Respect tenant and site permissions
• Validate API responses before usage
• No Secrets: Never put client secrets or API keys in client-side code.
• Least Privilege: Suggest the minimum required webApiPermissionRequests in package-solution.json.
• DOM Access: Never use document.getElementById. Use React useRef.
• Avoid dangerouslySetInnerHTML unless the content is sanitized

Testing & Quality

• Write unit tests for services and core logic
• Use Jest + React Testing Library for components and hooks
• Enforce ESLint and Prettier
• Keep dependencies updated
• Remove dead or commented-out code, unused imports and console logs before shipping

Accessibility

• Ensure keyboard navigation and visible focus states
• Provide labels and aria attributes for all interactive controls
• Validate color contrast when using theme tokens

Anti-Patterns to Avoid

• Hardcoded strings, colors, or dates
• Data access embedded in React components
• Direct DOM access instead of useRef
• Skipping error states or swallowing exceptions
• Rendering large lists without virtualization
• Accessibility regressions (missing labels, focus traps, low contrast)

Do / Don't (Quick Scan)

Do	Don't
Use strings.<Key> and placeholders	Hardcode user-facing strings
Use themeVariant and Fluent UI tokens	Hardcode hex colors
Centralize APIs in services	Call REST/Graph from components
Use @pnp/graph when available	Default to MSGraphClientV3
Add keyboard support and labels	Ship UI without a11y checks

Telemetry & Logging

• Use @pnp/logging or SPFx Log for error and diagnostic logging
• Never log secrets or PII

Checklist

Before generating SPFx code, follow these steps:

1. Context Check: Is this a Web Part, an Extension (Application Customizer, ListView), or a Library Component?
2. Environment Check: Check Environment.type (Local, SharePoint, Classic) to avoid errors during local workbench testing.
3. Dependency Check: Ensure @pnp/sp and @pnp/graph imports match v4+ syntax (imports from @pnp/sp/presets/all are deprecated; use selective imports like @pnp/sp/webs).
4. Error Handling: Wrap all async calls in try/catch blocks and define a UI state for errors.

Code Template: Functional Web Part

import * as React from 'react';
import * as ReactDom from 'react-dom';
import { Version } from '@microsoft/sp-core-library';
import { BaseClientSideWebPart } from '@microsoft/sp-webpart-base';
import { spfi, SPFx } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/lists";
import "@pnp/sp/items";

import { MyComponent } from './components/MyComponent';
import { IMyComponentProps } from './components/IMyComponentProps';

export interface IMyWebPartProps {
  description: string;
}

export default class MyWebPart extends BaseClientSideWebPart<IMyWebPartProps> {
  private _sp: ReturnType<typeof spfi>;

  protected async onInit(): Promise<void> {
    await super.onInit();
    // Initialize PnPjs
    this._sp = spfi().using(SPFx(this.context));
  }

  public render(): void {
    const element: React.ReactElement<IMyComponentProps> = React.createElement(
      MyComponent,
      {
        description: this.properties.description,
        context: this.context,
        sp: this._sp
      }
    );
    ReactDom.render(element, this.domElement);
  }

  protected onDispose(): void {
    ReactDom.unmountComponentAtNode(this.domElement);
  }

  protected get dataVersion(): Version {
    return Version.parse('1.0');
  }
}

Expected Outcomes

When this skill is applied, agent should:

• Generate idiomatic SPFx + React + TypeScript code
• Highlight and explain SPFx anti-patterns
• Enforce modular, service-based architecture
• Apply localization, Sass modules and API best practices
• Prefer modern tooling (Heft) and current guidance

Tone

• Clear, pragmatic and professional
• Explain why recommendations matter

Example Prompt

• Review this SPFx solution and refactor it using SPFx best practices, including localization, Sass modules, Graph & SharePoint access and Heft-based tooling.

Additional Prompt Examples

• Scaffold a new SPFx React web part using PnPjs v4, strict TypeScript, localization with loc and .module.scss styling.

• Refactor this web part to move all REST calls into services, add proper error handling and remove any hardcoded strings.

• Build an Application Customizer that injects a command bar using Fluent UI, with theme-aware styling and no hardcoded colors.

• Decide whether to use @pnp/graph or MSGraphClientV3 for this Graph call and explain why.

• Audit this solution for performance and accessibility issues, then provide prioritized fixes.

• Update this project to a Heft-based build and remove any nonstandard gulp customizations.

• Add a new web part to this existing SPFx solution, matching its architecture, localization and theming patterns.

• Add a Field Customizer to this solution using Fluent UI and theme tokens, with no direct DOM access.

• Migrate this legacy SPFx web part to a service-based architecture with PnPjs v4 and strict TypeScript.

Non-Goals

• Classic (non-SPFx) SharePoint customizations
• Backend-only implementations
• Over-optimization at the expense of readability