SPFx Workbench Retires Dec 1: 3 Changes to Make

The SharePoint hosted workbench retires on 1 December 2026. SPFx v1.23.0, released 13 May 2026, was the last version to ship support for it, so the page at /_layouts/15/workbench.aspx stops being a development target in a few weeks.

The replacement is not another isolated test page. It is debugging on a real modern page, with the SharePoint Framework Debug Toolbar appearing once the right query string parameters are present. That shift is mostly an upgrade, but it changes the daily workflow, and two separate changes in the last eighteen months have quietly invalidated most of the tutorials you will find for it.

In this post: Prerequisites · What you lose and what you gain · The easy path: serve configurations · The manual path: building the URL · Change 1: the manifest path moved · Change 2: the browser now asks permission · What the Debug Toolbar actually does · Extensions: one parameter per type · The localhost package alternative · Doing this in a production tenant · Who needs to change something? · Related reading

Prerequisites

An SPFx project on the Heft toolchain. The commands below use heft. On an older gulp project the equivalent is gulp serve, and the upgrade path is a separate job.
A modern page you can edit on a site where you have at least Edit rights, because debugging happens on a real page now.
The local dev certificate trusted so the browser will load https://localhost:4321 without complaint.
A current Chromium browser, Edge or Chrome. See the Local Network Access section below, because this one is not optional any more.

What you lose and what you gain

The honest summary is that the workbench was never a very good test environment. It only ever supported web parts and Adaptive Card Extensions. It could not load SPFx extensions at all, which is why anyone building an Application Customizer or a Field Customizer has already been debugging on real pages for years.

The workbench mimics a modern page canvas without being one. The width differs, not all theme colours apply, full-bleed layouts cannot be tested, and your web part never sits next to anybody else’s.

What you lose is convenience. The workbench was a blank canvas with nothing else on it, which made it fast and predictable. What you gain is a test that reflects reality: real theme, real page width, real neighbours, and the ability to test every component type through one workflow instead of two.

The easy path: serve configurations

Before hand-assembling URLs, check config/serve.json. The generator writes an entry there for each extension you scaffold, and each entry already contains the page URL and the component properties needed to debug it:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
      "customActions": {
        "d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
          "location": "ClientSideExtension.ApplicationCustomizer",
          "properties": { "testMessage": "Test message" }
        }
      }
    }
  }
}

Point the pageUrl at a real page on your own tenant, then launch that configuration by name:

heft start --serve-config=helloWorld

Heft opens the browser on that page with every required parameter already appended. For anything you scaffolded, this is the whole workflow, and editing serve.json once beats reconstructing a URL every morning.

The manual path: building the URL

For a web part on a page of your choosing, start the server without launching a browser, then append two parameters to the page URL:

heft start --nobrowser

https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/build/manifests.js

loadSPFX=true is the one people omit. For performance, SharePoint does not load the framework on a page with no registered components, so without this parameter nothing happens and nothing explains why. debugManifestsFile tells the loader to look at your machine instead of only the app catalog and the manifest server.

The page prompts you to confirm you are loading debug scripts. Accept once and it holds for the rest of the browser session, which is convenient until you forget it is on. To end a debug session without closing the browser or clearing session data, add reset=true to the URL.

Change 1: the manifest path moved

In SPFx v1.21 the development manifest URL changed from https://localhost:4321/temp/manifests.js to https://localhost:4321/temp/build/manifests.js. One extra path segment.

Every blog post, conference deck and internal wiki page written before that release carries the old path, and plenty written after it do too. The failure is quiet: the page loads, the toolbar may appear, and your component simply is not in the toolbox. If you are copying a debug URL from anywhere other than current documentation, check that segment first.

Change 2: the browser now asks permission

This one originates outside Microsoft entirely. Chromium 142, stable from 28 October 2025, introduced Local Network Access restrictions. A request from a public site to a loopback address is now gated behind a permission prompt, aimed at cross-site request forgery against routers and at local-network fingerprinting.

SharePoint Online loading your bundle from https://localhost:4321 is exactly that pattern. So Edge and Chrome now ask “Allow this site to access devices on your local network?” and you have to select Allow. Deny it, or dismiss it without reading, and the debug manifests never load and the component fails with no connection drawn to the prompt you just closed.

Chromium exposes this as two permission types, local-network for the private address space and loopback-network for localhost and 127.0.0.1. SPFx debugging needs the loopback one. If someone denied it once and cannot work out why debugging broke, that permission is where to look, not the SPFx project.

Once the parameters are present, SharePoint adds the Debug Toolbar to the page. It carries Show info for the loaded manifest, Hide bar to clear the chrome without leaving debug mode, Show developer dashboard, Log a bug which opens the sp-dev-docs issue list, Help, and Stop to kill debug script loading for the session.

Put the page into edit mode and a Web Part menu appears. It shows the selected web part’s data as JSON and HTML alongside its manifest details. That is more useful than it sounds if you ever script page creation, because it hands you the exact shape of a configured web part to reproduce programmatically.

Extensions: one parameter per type

Extensions need a parameter describing what to register, because there is no toolbox to drag them from. Application Customizers and List View Command Sets use customActions, keyed by the extension GUID from its manifest.json:

https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/build/manifests.js&customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{"location":"ClientSideExtension.ListViewCommandSet.CommandBar","properties":{"sampleTextOne":"One item is selected."}}}

The location value decides where commands render: ClientSideExtension.ListViewCommandSet.CommandBar for the top toolbar, ClientSideExtension.ListViewCommandSet.ContextMenu for the item menu, or ClientSideExtension.ListViewCommandSet for both. Application Customizers use ClientSideExtension.ApplicationCustomizer.

Field Customizers are the exception. They use a fieldCustomizers parameter keyed by the field’s internal name, with the extension GUID in an id property. Using the display name silently matches nothing.

The localhost package alternative

There is a second approach that avoids query strings altogether. Build and package without the --production argument and the resulting package references your local machine:

heft build
heft package-solution

Deploy that to the app catalog as normal, run heft start --nobrowser, and the web part can be added to any page, modern or classic, loading its code from your dev server. No parameters, no prompts after the first.

The obvious hazard is that this package is useless without your machine running. Deploy it to a catalog anyone else uses and the component fails for them with no clue as to why. Keep it to a dedicated development tenant or a site collection app catalog nobody depends on.

Doing this in a production tenant

Microsoft’s own documentation puts a caution on this, and it deserves repeating rather than skipping. Nothing technically stops you debugging a local solution on a production page. What you are doing is executing unreviewed code, in a real browser session, against real data, on a page other people may open.

A debug session persisting for the whole browser session makes that slightly sharper than it first appears. The practical answer is a development tenant, or at minimum a page in a site nobody else uses, plus reset=true as a habit when you finish.

Who needs to change something?

You still open the hosted workbench by habit. That page stops working on 1 December. Set up a serve configuration pointing at a real page and switch now, while you can compare the two.
Your team has an onboarding doc with a debug URL in it. Check the /temp/build/manifests.js segment. A doc written before SPFx v1.21 sends every new developer down a silent failure.
Someone’s debugging “just stopped working” recently. Check the browser’s local network permission for that site before touching the project.
You only build extensions. Nothing changes for you. You were never able to use the workbench anyway, and the parameters above are what you already do.
You are still on a gulp toolchain. The retirement is the smaller of your two problems, and the toolchain migration is the one to schedule first.

Start your SharePoint with SPFx covers the toolchain context behind these commands, including why the local workbench disappeared long before the hosted one.
SPFx Folder Structure Explained explains where config/serve.json sits and what else in that folder the toolchain reads.
Rendering SharePoint List Extensions for Specific List Templates goes deeper on the extension types that could only ever be debugged this way.

Retirements usually mean replacing something good with something adequate. This is the rarer case where the replacement is genuinely better, since testing on a page that behaves like a page beats testing on an approximation of one. The friction is entirely in the setup, and most of it comes from the two changes above rather than from the Debug Toolbar itself.

My own guess is that the local network permission will cause more lost hours this December than the retirement does. Comments are open if you have seen it bite somebody.