SharePoint Framework v1.5.0 Docker image available with some caveats

I’ve just published the SharePoint Framework v1.5.0 Docker image. But there is a caveat to use it.

SharePoint Framework in Docker

Using SharePoint Framework in Docker containers offers you a number of benefits. For one, you don’t need to install Node.js or any of the open source packages on your host machine. But maybe what’s even more important, is that you can easily switch between the different versions of the SharePoint Framework. The longer you use the SharePoint Framework to build solutions for your organization, the more important this will become. It’s just a matter of time before you end up with a number of projects, each built using a different version of the SharePoint Framework. Whenever you will need to add a new component to the project, being able to use the same version of the SharePoint Framework as when you created the project, will be essential for you to ensure that the project will keep working as expected.

To help you use SharePoint Framework with Docker, for each released version of the SharePoint Framework, I’ve published a Docker image with the SharePoint Framework Yeoman generator preinstalled. And while it used to just work in the past, there is a ceveat to using it with SharePoint Framework v1.5.0.

Inconvenient SharePoint Framework v1.5.0 and Docker

Scaffolding a project using the SharePoint Framework Yeoman generator v1.5.0 works just as expected. But when you run the gulp serve task and try to open the local workbench, all you will see in the browser is an error.

Error displayed in the browser when trying to open the local workbench served from a Docker container

The same will happen, if you tried to test your web parts in the hosted workbench.

Error displayed when opening the hosted workbench trying to load bundles served from a Docker container

The issue

The issue is caused by the gulp-connect package used by the gulp serve task. Last January, this package has been updated and binds the http server to the specified host. If no host is specified, gulp-connect binds the server to localhost. While you can specify the host name to use in the serve.json file, that name isn’t passed to the gulp-connect task. As a result, the server is always bound to localhost which makes it inaccessible outside of the Docker container. In the previous versions of gulp-connect, no host name was used, which caused the server to be bound to 0.0.0.0 and which exposes the local server outside the Docker container.

The fix

Ideally, the host name specified in the serve.json file would be passed to the gulp-connect package. Then, whenever you wanted to use SharePoint Framework in a Docker container, you would specify 0.0.0.0 as the host name which would allow you to access the workbench from the host. This fix to the gulp serve task has been merged by the SharePoint engineering yesterday and will be available in the future versions of the SharePoint Framework.

A workaround

If you want to use SharePoint Framework v1.5.0 in Docker, you need a workaround. The easiest one is, to edit the ./node_modules/gulp-connect/index.js file and change line 106 from:

return this.server.listen(this.port, this.host, (function(_this) {

to (remove the this.host argument):

return this.server.listen(this.port, (function(_this) {

Since you’re editing a dependency here, you will need to do this each time you restore your project dependencies. Not optimal, but works.

Summary

A change in the gulp-connect package makes it impossible to use SharePoint Framework v1.5.0 in a Docker container. A fix has been applied and will be made available in the future versions of the SharePoint Framework. If you want to use SharePoint Framework v1.5.0 in Docker, you need to apply a patch to the gulp-connect package.

Others found also helpful: