Debug SharePoint Framework solutions in Visual Studio Code

Visual Studio Code is a popular code editor frequently used for building SharePoint Framework solutions. By setting up debugging of your SharePoint Framework solution in Visual Studio Code, you can more efficiently step through your code and fix errors. This article describes the prerequisites and configuration steps required to configure Visual Studio Code for debugging SharePoint Framework solutions.

Prerequisites

The easiest way to configure Visual Studio Code to debug SharePoint Framework solutions is by using Google Chrome and the Debugger for Chrome Visual Studio Code extension.

Install Google Chrome

Install the Debugger for Chrome Visual Studio Code extension

Start Visual Studio Code and open the Extensions pane.

In the search box, search for Debugger for Chrome.

Install the Debugger for Chrome extension by clicking the Install button, next to the extension. After the extension has been installed, reload the Visual Studio Code window by clicking the Reload button.

Debug SharePoint Framework solution using local workbench

When building SharePoint Framework solutions, you can use the local workbench to verify that your web part is working correctly. Using local workbench is convenient for testing all scenarios that do not require communicating with SharePoint as well as for offline development.

Create debug configuration for local workbench

In Visual Studio Code activate the Debug pane.

In the top section of the pane, open the Configurations drop-down and select the Add Configuration... option.

This configuration uses the chrome debugger provided with the Debugger for Chrome extension. It points to the URL of the local workbench as the starting point. What is essential in debugging TypeScript code, is the configuration of source maps that the debugger uses to map the JavaScript running in the browser to the original TypeScript code.

Test debugging SharePoint Framework client-side web part in the local workbench

With Visual Studio Code configured for debugging SharePoint Framework solutions using Google Chrome and the local workbench, you can verify that everything is working as expected.

Configure a breakpoint

In Visual Studio Code open the main web part source file and add a breakpoint in the first line of the render method by either clicking on the margin left to the line number or by highlighting the code line in the editor and pressing the F9 key.

Start serving the SharePoint Framework solution

In Visual Studio Code, from the View menu select the Integrated Terminal option or press CTRL+` on the keyboard. In the terminal run the following command:

gulp serve --nobrowser

Running this command will build your SharePoint Framework solution and start the local webserver to serve the output files. Because the debugger will start its own instance of the browser, you use the --nobrowser argument to prevent the serve task from opening a browser window.

Start debugging in Visual Studio Code

Once the gulp task is finished, move the focus to the code area of Visual Studio Code and press F5 (or from the Debug menu select the Start Debugging option). The debug mode in Visual Studio Code will start, changing the color of the status bar to orange and a new window of Google Chrome will open showing the local version of the SharePoint workbench.

Note, that at this point the breakpoint is disabled, because the web part's code hasn't been loaded yet. SharePoint Framework loads web parts on demand only after they have been added to the page.

Add web part to canvas

To verify that debugging is working, in the workbench add your web part to the canvas.

Notice, that with the code loaded on the page, the breakpoint indicator changed to active.

If you now reload the page, your breakpoint in Visual Studio Code will be hit, and you will be able to inspect all properties and step through the code.

Debug SharePoint Framework solution using hosted workbench

When building SharePoint Framework solutions that communicate with SharePoint you might want to verify the interaction between your solution in SharePoint. To do this easily, you can use the hosted version of the SharePoint workbench which is available on every Office 365 tenant at https://yourtenant.sharepoint.com/_layouts/workbench.aspx. When building SharePoint Framework solutions, you will be doing such tests regularly and it is a good idea to create a separate debug configuration for the hosted version of the SharePoint workbench.

Create debug configuration for hosted workbench

In Visual Studio Code open the ./.vscode/launch.json file. Copy the existing debug configuration and use the URL of the hosted workbench:

With the debug configuration for the hosted workbench ready, verify that it's working correctly. In Visual Studio Code, activate the Debug pane and in the Configurations drop-down, select the newly added Hosted workbench configuration.

Next, start debugging either by pressing the F5 key or by selecting from the Debug menu the Start Debugging option. Visual Studio Code will switch into debug mode, indicated by the orange status bar, and the Debugger for Chrome extension will open a new instance of Google Chrome with the Office 365 login page.

After you log in, add the web part to the canvas and refresh the workbench, just like with the local workbench, you will see the breakpoint in Visual Studio Code be hit and you will be able to inspect variables and step through the code.