Troubleshooting SPFx running in a Docker Container

I recently had a chance to do a “3 city tour” for the Global Microsoft 365 Developer Bootcamp in Iselin, NJ, Malvern, PA, and NYC. I got to present alongside Tom Daly and Manpreet Singh. During the NYC event, we were joined by Peter Ward who presented the 4th session. (Session Info)

During those presentations, I walked our audience through setting up their development environment. That included, creating a tenant, setting up the app catalog, installing node, gulp, yeoman, and the spfx yeoman generator. We saw all sorts of errors during this session, from permissions issues, to version conflicts. Because of those issues, I mentioned during each session that Docker is a good way to avoid the issues that we were facing and a good way to speed up setting up an environment for new developers or new project members.

Setting up Docker was beyond the scope of these sessions because of time and we had all levels of experience in the rooms. From people who never wrote a line of code to experts.

Once you have Docker up and running, there are a few steps that you’ll need to do before you can get your spfx web part running. For this post, I am using a Docker image that was built from node:8.9.4 and I am using SPFx 1.9.1. I also created a simple SPFx web part with all the defaults. Node 10 is the recommended version.

I won’t walk through setting up Docker here. I’m assuming you have it installed and understand how to run a container. If not, Waldek Mastykarz is a good source for getting started.

Workbench is Unreachable

Once you have a solution, the first thing you likely will try to do is run a gulp serve to make sure everything is running and instead of being able to access the workbench, you’ll be greeted with the following.

In order to fix the unreachable page, you’ll need to make edits to the serve.json file found in your project’s config folder.

The old file will look like this:

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "initialPage": "https://localhost:5432/workbench",
  "api": {
    "port": 5432,
    "entryPath": "node_modules/@microsoft/sp-webpart-workbench/lib/api/"
  }
}

We need to add a hostname that points to 0.0.0.0. Your new serve.json should look like the following.

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "hostname": "0.0.0.0",
  "initialPage": "https://localhost:5432/workbench",
  "api": {
    "port": 5432,
    "entryPath": "node_modules/@microsoft/sp-webpart-workbench/lib/api/"
  }
}

Running a gulp serve again should fix the workbench.

SPLoaderError

The next issue comes when trying to load the web part. You’ll see an SPLoadedError.loadComponentError message. I’ve seen the web part work the first time you drop it on the page, but then this error comes up after refreshing or adding the web part on the page a 2nd time.

Go to the following path in your project: \node_modules\@microsoft\sp-build-web\lib\SPWebBuildRig.js. In that file, somewhere around line 91, you’re going to find the following:

const serve = spBuildCoreTasks.serve;
        spBuildCoreTasks.writeManifests.mergeConfig({
            debugBasePath: `${serve.taskConfig.https ? 'https' : 'http'}://${serve.taskConfig.hostname}:${serve.taskConfig.port}/`
        });

After the first line that sets the serve constant, you’re going to want to wrap the mergeConfig logic with an if statement. It should look like the following when you’re done.

 if (!spBuildCoreTasks.writeManifests.taskConfig.debugBasePath){
            spBuildCoreTasks.writeManifests.mergeConfig({
                debugBasePath: `${serve.taskConfig.https ? 'https' : 'http'}://${serve.taskConfig.hostname}:${serve.taskConfig.port}/`
            });
        }

You also need to set the debugBasePath that is referenced. In order to do that, you’ll need to go to \config\write-manifest.json and add the debugBasePath with the localhost as seen below.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/write-manifests.schema.json",
  "cdnBasePath": "<!-- PATH TO CDN -->",
  "debugBasePath": "https://localhost:4321"
}

Once those 3 steps are done, you should have a functioning web part. Just make sure you re-run gulp serve and load the page from https://localhost:5432/workbench. That will redirect you to https://localhost:4321.