SharePoint Framework Deployment and Debugging Tips

The SharePoint Framework (SPFx) is a “page and web part model” that provides full support for client-side SharePoint development. With the SharePoint Framework, you can build apps in SharePoint using modern web technologies and tools in any development environment. The SharePoint Framework works for SharePoint Online and also for on-premises installations of SharePoint 2016 (Feature Pack 2) and higher.

This blog will discuss a few critical steps for getting your SPFx deployed to production.  We’ll cover how to package the solution, how to add logging for your solution, how to debug your code even while in production, and finally, how to properly package and deploy updated versions of your solution.

Initial Deployment

After testing your SPFx solution, prepare it to go to SharePoint Online by using Gulp:

gulp package-solution --ship
The “--ship" flag tells gulp to package the solution for use in production and not rely on the workbench. This includes additional steps such as webpack, which will minify and optimize your code for hosting in SharePoint Online.

Copy your sppkg file to the App Catalog in your SharePoint Online environment and select “Deploy.”  If done correctly, your target will be “SharePoint Online.”

Logging

First make sure that PnPJS Logging is installed:

npm install @pnp/logging

Next, add it as required in your project:

import { Logger, LogLevel, ConsoleListener } from "@pnp/logging";

Then initialize the Logger:

Logger.activeLogLevel = LogLevel.Info;
Logger.subscribe(new ConsoleListener());

Now you have logging actions available that will log to the console. This is extremely helpful when debugging your SPFx solution. You can call the logger with the following command(s):

Logger.write('log a simple message');
Logger.write("log a message and specify log level", LogLevel.Error);

The above example of logging an error to your browser console would look like this:

This logging comes in handy for monitoring your application without alerts or for manually stepping through your code.

Debug in Production

If you’re encountering issues with your SPFx web part and want to see what exactly is going on in production, it’s actually possible to debug your code in production.  Typically, this would not be possible after webpack minifies your code.  In order to start debugging, add the following string to your querystring:

loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js

This will cause a prompt, asking if you want to load these scripts:

Click “Load debug scripts” and make sure “gulp serve” is running locally or else you’ll receive this error:

This will now allow you to step-through your code in production to help track down what might be going on. There’s a catch with this. If you strip out these new querystring values, the debugging will not end.  In order to stop SPFx from loading your local files, you need to reset it with this querystring value.  Otherwise, you will continue to get the “Allow debug scripts?” prompt.

&reset=true

Updating SPFx Solutions

Initially, to get your solution ready to deploy to SharePoint Online, you only need to execute the command “gulp package-solution –ship.” But updating your solution requires a few more commands.

In your command window at the root of your solution, execute the following commands in order:

gulp build
gulp bundle --ship
gulp package-solution --ship

This will produce a new sppkg file that contains all your recent updates. The first two commands are critical in ensuring your solution includes all of your latest files. By skipping the first two commands, gulp will package your initial build.  Make sure not to miss these steps when pushing your changes to production.

Recap

This article covered how to package your SPFx solution for deployment and how to ensure subsequent repackaging includes all of your changes. The PnPJS logger will also help you understand the timing and execution of your code and, if needed, you can step-through your code, even in production. Hopefully this article helps you with your next SPFx deployment. But if you still have questions, please don’t hesitate to reach out to us. We’d love to help you get started.