Debug SharePoint Framework solutions in Visual Studio Code

Use Visual Studio Code's built-in JavaScript debugger to set breakpoints, inspect variables, and step through SharePoint Framework (SPFx) code running in Microsoft Edge or Google Chrome.

For web parts and extensions, debug on actual SharePoint pages with the SharePoint Framework Debug Toolbar (developer toolbar). This article uses the Heft-based toolchain in SPFx 1.22 and later. For older projects, use the commands for the legacy gulp-based toolchain.

Prerequisites

• Set up your development environment with the dependencies supported by your project's SPFx version.
• Install a current version of Visual Studio Code and Microsoft Edge or Google Chrome. A separate Debugger for Chrome extension isn't required.
• Use a development SharePoint site and a modern page that you can edit. For Field Customizers and ListView Command Sets, use a suitable list or library view.
• Install project dependencies and trust the local HTTPS certificate by running heft trust-dev-cert from the project folder.

Debug configurations

Open .vscode/launch.json in the project folder. If the generator created a Hosted workbench configuration, replace it with a configuration targeting your development page.

The following configuration uses Microsoft Edge. Replace the example site and page with your own URL:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "SharePoint page",
      "type": "msedge",
      "request": "launch",
      "url": "https://contoso.sharepoint.com/sites/dev/SitePages/Test.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/build/manifests.js",
      "webRoot": "${workspaceFolder}",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "webpack:///.././src/*": "${webRoot}/src/*",
        "webpack:///../../../src/*": "${webRoot}/src/*",
        "webpack:///../../../../src/*": "${webRoot}/src/*",
        "webpack:///../../../../../src/*": "${webRoot}/src/*"
      }
    }
  ]
}

To use Google Chrome, change type to chrome. Both browser types use the built-in JavaScript debugger.

The manifest URL above applies to SPFx 1.21 and later, including Heft-based SPFx 1.24 projects. Earlier projects use https://localhost:4321/temp/manifests.js. Use your project's configured HTTPS port if it isn't 4321. If the page URL already has query parameters, append the debug parameters with & instead of a second ?.

Configure a breakpoint

1. Open your web part source file and set a breakpoint in render() by selecting the margin beside the line number or pressing F9.

2. Open the integrated terminal in Visual Studio Code.

3. From the project folder, start the local development server:

   heft start --nobrowser
   

4. Wait for the initial build to complete and leave the server running.

Start debugging in Visual Studio Code

1. In Run and Debug, select SharePoint page and press F5.
2. Sign in to the development tenant in the browser window opened by the debugger.
3. Select Load debug scripts only when the manifest URL points to your trusted development server.
4. Edit the page and add your local web part from the toolbox. The Debug Toolbar is available while debugging is enabled.
5. When the web part loads, the breakpoint becomes active. If necessary, reload the page to hit it.

Local web parts are loaded on demand, so a breakpoint might remain unbound until the component is added to the page. If a breakpoint doesn't bind, confirm the local build succeeded, the manifest URL is reachable, the development certificate is trusted, and the source map paths match your project.

Use Stop on the Debug Toolbar when you're finished to disable loading debug scripts for the browser session.

Debug extensions

Extensions must be tested on an appropriate modern SharePoint page, list, or library, not in a workbench. Configure the extension's serveConfigurations in config/serve.json, or add its debug parameters to the page URL in .vscode/launch.json.

The parameters depend on the extension type. An Application Customizer uses customActions with its manifest ID and ClientSideExtension.ApplicationCustomizer location; Field Customizers and ListView Command Sets require their own parameters. See Debug SharePoint Framework extensions on modern SharePoint pages for the configuration and URL formats.

Set a breakpoint in the extension's initialization or event handler, start the local server, and launch the matching page configuration with F5.

Debug solution using hosted workbench

The SharePoint Online workbench is no longer the recommended debug target. Replace existing hosted-workbench launch configurations with the SharePoint page configuration above. The local workbench was removed in SPFx 1.13.

For Copilot UX components, use the fully supported Copilot Workbench and its host-specific setup.

See also

• Debug SharePoint Framework solutions on modern SharePoint pages
• SharePoint Framework Debug Toolbar
• Yeoman generator for the SharePoint Framework
• SharePoint Framework Overview