Azure / Office 365 / SharePoint Development / Search

How to debug your SharePoint Framework web part

August 19, 2016

Already a great number of blog posts have been written about the new SharePoint Framework release two days ago. With every new tool or framework, there is a learning curve. The best way of learning how the SharePoint Framework works is by reading the code and debugging it.

This article focusses on how you can quickly debug your web part created with the SharePoint Framework.

Important: this article is written for Chrome. The experience in other browsers can vary a bit.

Using debugger statement

The SharePoint Framework makes use of a tool called webpack. Webpack is just great, you can do many things with it, but the overall use is for generating a bundled JS file. When you are going to run gulp serve it will bundle all the files into a single JavaScript file. This single JavaScript file contains a lot of content.

If you want to set a breakpoint to debug your code, it takes some time before you found the right line. An easier way is by setting a debugger statement in your source file.

Debugger statement in your code

Debugger statement in your code

Save this change and open your browser developer tools (or refresh the page with the dev tools open). Once the page gets reloaded, your developer tools will stop on the debugger statement.

Debugging your code with the debugger statement

Debugging your code with the debugger statement

Debugging the TypeScript files

As mentioned, the SharePoint Framework bundles everything in one large JavaScript file.

SPFx bundle file

SPFx bundle file

Debugging this large JS file is a hell of a job and it is JavaScript. Your source files are written in TypeScript, so the code you are going to debug is not the same.

Luckily there is something called source maps. Source maps is not something new, these were used a couple of years ago to easily debug minified code (JavaScript and also CSS) where it was used to provide you a mapping from the minified code to the original code.

When you are writing TypeScript and transpiling the code to JavaScript. You have the option to include a source map reference at the bottom of the file. The SharePoint Framework will automatically do this, so you do not have to worry about it.

Source map reference

Source map reference

The great thing about these source maps is that your browser can read them and load the original code. If you take a look in the sources, you will see a webpack:// reference:

Webpack

Webpack

If you open this, you will see that all the original files are loaded and you can navigate to your original web part TypeScript files:

All the original files

All the original files

Important: check that you have enabled JavaScript source maps in your browser settings.

Enable JavaScript source maps

Enable JavaScript source maps

Once you found the file you were looking for, you can set a breakpoint in it and start debugging:

Debugging the original files in Chrome

Debugging the original files in Chrome

Info: Andrew Connell wrote a great article about debugging and sourcemaps last week: Debugging Node.js projects with TypeScript and VS Code - Digging into Sourcemaps

Debugging in Visual Studio Code

You can also use Visual Studio Code to debug your web part. To do this, you will have to install an extension called VS Code – Debugger for Chrome. The extension can be found here: Chrome debugger extension.

VS Code - Debugger for Chrome

VS Code - Debugger for Chrome

Info: there are other ways of debugging in Visual Studio Code, but this requires the least configuration.

Once you have installed it, you have to do the following configuration: extension configuration.

  • Create a launch.json file in the .vscode folder;
  • Add the following configuration code to it:

Before drop 6

Drop 6

As of Drop RC0 and onwards

  • Press F5 to start a new debugging session;
  • Another way to open Chrome with the debugging port is via the command prompt and specifying the remote debugging port argument: --remote-debugging-port=9222

Important: it might occur that the Visual Studio Code debugger mentions that it cannot attach. Best is to close all the Chrome sessions (check in your task manager) and start Chrome again with the remote debugging port.

  • Once you started Chrome, start gulp serve (you can keep this running in the back);
  • Now you can press F5 in Visual Studio Code and you are ready to debug your code;
  • Place a breakpoint somewhere in your web part and add it to the workbench. You will see that Chrome will pause and tells you that you can debug it in Visual Studio Code.
Chrome paused for VSCode debugging

Chrome paused for VSCode debugging

VSCode debugging

VSCode debugging

Happy coding with the SharePoint Framework.

Update

Microsoft released its own article of how you could debug your SharePoint Framework projects, you can find the article here: Debug SharePoint Framework solutions in Visual Studio Code.

Comments

  • Luis Valencia – MVP

    any idea how to do the same on mac?

  • Michel

    The launch.json configuration mentioned in the post is outdated and will not find your files.
    I worked it out – this is working with Sharepoint Framework Developer Preview Drop 6 (released 22, 2016).

  • Rick Kushner

    In my launch.json, the type “chrome” give the error “”Value is not an accepted value”, “url” & “webRoot” both give the error message: “Property x is not allowed”

    The version at the top of the launch.json file is 0.2.0.

    • Try to remove the launch.json file, and let VSCode recreate it and try out the default configuration.

  • John Rennemeyer

    How about connecting the debugger to a test server deployed instance of the webpart (including sourcemaps)? I’m trying to get the sourceMapPathOverrides working, but have been unsuccessful so far.

  • Michel

    And changed again with RC0:

  • Pingback: Webinar Recap: Building Client-Side Web Parts with the SharePoint Framework - Rencore()

  • When the web part is hosted in the CDN, you mean that you are using a production version (–ship). This one is harder to debug, as it is minified and not using any source mapping reference. So you cannot link it to the original code in your TS file.

    What you could do is setup another environment that uses the developer bundle instead of the production one. That way you have the source mapping reference and are able to debug the original files.

    • Hi Elio,
      That’s exactly what I tried yesterday and got it to work