Include source maps in your SharePoint Framework package

When you need to test your solutions outside the workbench environment, it can be difficult to inspect the minified code and see what’s going on.

Fortunately, there are ways for the browser to un-minify the code back to its original development state through the magic of source maps.

These wonderful files, when deployed alongside your final scripts, will let the browser know how the code was originally shaped, allowing you to browse through it as if it were never minified and compressed at all.

Using source maps in SPFx solutions

Last year, Waldek Mastykarz wrote a very useful article on how to debug production versions of spfx projects by generating our code’s source maps and passing them on to chrome.

While this process certainly does the job, having to deploy the files into a server and manually pointing chrome their way can become very tedious process when done more than a couple times.

The ideal scenario would be for SPFx solutions to provide a built-in way to generate our packages with the source maps already included. But since that’s not the case for the moment, let’s try and to it ourselves.

Generate the source maps

By default, when generating our solutions for production, the SPFx toolchain does not generate the source map files as it would when generating for the workbench.

To force the creation of these files, we can implement Waldek’s solution by changing our gulpfile’s contents to:

'use strict';

const gulp = require('gulp');
const build = require('@microsoft/sp-build-web');
const webpack = require('webpack');
build.addSuppression(`Warning - [sass] The local CSS class 'ms-Grid' is not camelCase and will not be type-safe.`);

build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfiguration) => {
    generatedConfiguration.devtool = 'source-map';

    for (var i = 0; i < generatedConfiguration.plugins.length; i++) {
      const plugin = generatedConfiguration.plugins[i];
      if (plugin instanceof webpack.optimize.UglifyJsPlugin) {
        plugin.options.sourceMap = true;
        break;
      }
    }

    return generatedConfiguration;
  }
});

build.initialize(gulp);

Try packaging your project now with gulp bundle --ship and gulp package-solution --ship and you’ll see the source map file was created in the dist folder.

Now we need to make sure it’s included in the final .sppkg package file.

Add the files to the final package

Once you package your project, a debug folder will be created in the sharepoint

\solution\ directory alongside the package file. The contents of this folder are the same as the package, but extracted so you can check and validate its contents.

Inside we have a ClientSideAssets folder where all our resources are located. This is where we’ll place our source map files.

But even if we copy our file here, SharePoint will still ignore it during deployment, so we need to make a couple more changes.

In the _rels folder, we can find the ClientSideAssets.xml.rels file which instructs SharePoint on which files are to be deployed and what their purpose is. Each of the resources listed here have a sequential id so when we create a new entry in the file, we need to make sure it doesn’t clash with any others. The last id in the sequence can be found in the AppManifest.xml.rels file so give that a peek before creating a new entry. For the Target attribute, we should use the path to our source map file.

Finally, in the [ContentTypes].xml file we need to establish how our file should be interpreted by the browser by adding a new entry for the map extension and declaring it as an application/json file.

Repackage and deploy to SharePoint

With these changes done, all that’s left is to package these files into a valid .sppkg file that we can deploy into SharePoint.

Fortunately, the package file is a simple zip with a different extension so all we need to do is select the contents of the debug folder and create a zip file with them, then change the file extension to .sppkg.

And now for the moment of truth, upload your new package file to an app catalog and when prompted, deploy . If everything was done right, it should deploy as usual.

Now when you go into the page and open your developer tools, if you open the developer tools you should see the original files ready for you to debug.

Automate the whole thing

In a real world scenario, we don’t want to do this whole process by hand, so we should create a gulp task to automate it.

You can find an example project in this repo where the task has been created in the insertSourceMapsTaks.js and called in the gulp file. The code is commented so knowing the process by hand, it should be pretty simple to follow what’s going on.

Using this method, I hope I can save you some time in debugging your projects outside of the workbench environment.

1 comment on “Include source maps in your SharePoint Framework package

  1. Pingback: SharePoint Dev Weekly - Episode 32 - Office 365 Developer Blog

Leave a Reply

Your email address will not be published. Required fields are marked *