SPFx Local Workbench

A Visual Studio Code extension that brings back the local workbench for testing SharePoint Framework (SPFx) web parts and Application Customizers without deploying to SharePoint.

Microsoft removed the local workbench in SPFx 1.13+. This extension restores that functionality with a custom-built workbench environment that simulates the SPFx runtime and adds additional developer tooling.

Features

Web Parts

• Automatic SPFx Detection: Automatically detects SPFx projects in your workspace
• Web Part Discovery: Parses all web part manifests from your project
• SPFx Runtime Environment: Custom-built workbench that simulates the SPFx runtime with AMD module loading
• Property Pane: Full property pane support for configuring web parts
• Live Reload Support: Works with heft start for real-time development
• Multiple Web Parts: Add, configure, and test multiple web parts simultaneously on the canvas
• Theme Support: Choose from standard SharePoint themes and even use your own directly within the workbench

Application Customizers

• Extension Discovery: Automatically detects Application Customizer manifests alongside web parts
• Header & Footer Placeholders: Simulated Top and Bottom placeholder zones, just like SharePoint
• Interactive Add/Remove: Use the + button in the header zone to add extensions from a picker
• Property Editing: Click the edit (pencil) icon on a loaded extension to modify its ClientSideComponentProperties and re-render
• PlaceholderProvider Mock: Full mock of context.placeholderProvider including tryCreateContent() and changedEvent

Storybook Integration (Beta)

• Auto-Generated Stories: Automatically generates Storybook stories from your SPFx component manifests
  • Locales: Creates story variants for each locale defined in your component
  • Preconfigured Entries: Creates story variants for each preconfigured web part entry in your manifest
• SPFx Context: Custom Storybook addon provides full SPFx context and theme switching
• Visual Testing: Test components in isolation with different themes and contexts
• Live Development: Run Storybook alongside your SPFx project for component development

API Proxy & Mock System

• Drop-in HTTP client replacements: SPHttpClient, HttpClient, and AadHttpClient are replaced with proxy-aware classes — no code changes needed in your web parts
• Configurable mock rules: Define URL matching rules with inline or file-based JSON responses
• Glob pattern matching: Match URLs with wildcards (e.g., /_api/web/lists/getbytitle('*')/items)
• Client type filtering: Target rules to specific client types (spHttp, http, aadHttp)
• Hot reload: Edit your mock config and rules are reloaded instantly
• Request logging: All proxied calls are logged to the "SPFx API Proxy" output channel
• Fully optional: Disable the proxy to use real fetch() calls with external tools like Dev Proxy

Full proxy documentation → — architecture, setup guide, mock rule reference, and examples.

Mock data generation → — status code stubs, JSON/CSV import, request recording, and more.

Requirements

• VS Code 1.100.0 or higher
• An SPFx 1.22+ project (Heft-based)
• Node.js and npm/pnpm/yarn

Getting Started

1. Open your SPFx project in VS Code
2. Start your SPFx development server: Run heft start --nobrowser in a terminal
3. Use the Command Palette (Ctrl+Shift+P) and search for "SPFx: Open Local Workbench" or click the button in the task bar

Usage

Opening the Workbench

There are several ways to open the workbench:

1. Command Palette: Ctrl+Shift+P → "SPFx: Open Local Workbench"
2. Status Bar: Click the "SPFx Workbench" status bar item (shown when an SPFx project is detected)
3. Quick Command: Use "SPFx: Start Serve & Open Workbench" to start everything at once

Starting Development Server

Use the command "SPFx: Start Serve & Open Workbench" to:

1. Start heft start in a terminal
2. Open the workbench after a short delay

How It Works

This extension provides a custom-built workbench environment that simulates the SPFx runtime:

1. A TypeScript-based workbench runtime is bundled with the extension
2. When you open the workbench, it loads in a VS Code webview
3. An AMD module loader shim allows SPFx bundles to load and register their modules
4. Mock SharePoint context and APIs are provided to web parts
5. The runtime fetches your web part bundles from https://localhost:4321
6. Your web parts render in a simulated SharePoint environment
7. Application Customizers are loaded the same way, with mocked Top/Bottom placeholder zones rendered above and below the canvas

Using Storybook for Component Development

The extension includes Storybook integration for visual testing and component development:

1. Generate Stories: Run "SPFx: Generate Storybook Stories" from the Command Palette

   • Stories are auto-generated from your component manifests
   • Each localized variant gets its own story
   • When enabled (default), stories are generated automatically when starting the server but there is also a dedicated button in the panel's title bar

2. Add Your Own Stories: Add additional stories to your project as needed

   • Any stories.ts files anywhere within your src directory will be picked up
   • Vary by property values, mock config, theme, locale, and more

3. Open Storybook: Run "SPFx: Open Storybook" to launch the Storybook dev server

   • View opens in a VS Code webview panel
   • Includes toolbar for theme and display mode switching

4. SPFx Addon: The custom @spfx-local-workbench/storybook-addon-spfx addon provides:

   • Full SPFx context mock (same as workbench)
     • Including per story mock configurations
   • Theme switcher with all Microsoft 365 themes and support for custom themes
   • Hot reload support during development

5. Story Structure: Auto-generated stories follow CSF 3.0 format:

   import type { Meta, StoryObj } from '@storybook/react';
   
   import HelloWorldWebPart from './HelloWorldWebPart';
   
   const meta: Meta<typeof HelloWorldWebPart> = {
     title: 'WebParts/HelloWorld',
     component: HelloWorldWebPart,
     parameters: {
       spfxContext: {
         /* ... */
       },
     },
   };
   
   export const Default: StoryObj = {};
   

Commands

Configuration

General Settings

Theme Settings

Note: The extension includes 10 default Microsoft 365 themes: Teal, Blue, Orange, Red, Purple, Green, Periwinkle, Cobalt, Dark Teal, Dark Blue. Themes are identified by their name property (case-sensitive). Custom themes defined here also appear in the Storybook theme toolbar under "From your organization".

Context Settings

Customize the mock SharePoint context:

The pageContext object includes:

• site: Site collection information (absoluteUrl, id)
• web: Web information (absoluteUrl, title, description, templateName, id)
• user: User information (displayName, email, loginName, isAnonymousGuestUser)
• cultureInfo: Culture/locale information (currentCultureName)
• isNoScriptEnabled: Whether NoScript is enabled
• isSPO: Whether this is SharePoint Online

You can add additional properties as needed to match your SPFx solution requirements.

Storybook Settings

Proxy Settings

See PROXY.md for the full mock rule reference, architecture details, and examples.

Troubleshooting

Having issues? See the Troubleshooting Guide.

License

MIT License - See LICENSE file for details.