Using Docker images for building SharePoint Framework solutions offers you great flexibility. But only when you make the image your own, you will truly benefit of it.

What is Docker

Docker is a light-weight virtualization technology. Where the size of the virtual machines you used in the past for SharePoint development were measured in gigabytes, Docker images are usually a few hundred megs big. The most significant difference between Docker images and VMs is, that they are easier to create and manage.

Docker images usually run on Linux. This is why, for a long time, there was no place for them in the SharePoint development ecosystem. But not anymore. The SharePoint Framework development toolchain is cross-platform and is a perfect fit for use with Docker images.

Why should you care about Docker if you’re building SharePoint Framework solutions

Over the last few months, we’ve seen a number of releases of the SharePoint Framework toolchain. Despite the recommendation to stay on the latest version of the toolchain, it’s hardly the reality. If you start a project today, most likely, you won’t update the version of the SharePoint Framework you’re using unless you really have to. And once the solution you’ve built is deployed to production, you won’t update the underlying version of the SharePoint Framework if all you have to do is a single change. It’s not worth the effort and the hours, not to mention possible regression errors an update could introduce.

Using Docker, you can easily create an image for each version of the SharePoint Framework toolchain and switch between them in a matter of seconds. You can put in a Docker image a single node package, but also a complete Node dependency chain including Node itself which allows you to use the latest version of Node.js supported by the given version of the SharePoint Framework. Not to mention, it helps you keep your host machine clean and ensure that everything will work, also on other machines than your own.

SharePoint Framework Docker images

To help you get started using Docker with the SharePoint Framework, with each release of the SharePoint Framework, I’ve been publishing a new ready-to-use Docker image. If you want to try a new version of the SharePoint Framework, all you have to do is run one command in the command prompt, and you’re good to go. But you should take it a step further.

SharePoint Framework Docker image for your team

Docker images are composed of layers. Each layer builds on top of another layer, adding some specific elements like configuration or tools. The Docker image I built is based on Node.js and adds only the SharePoint Framework toolchain. It’s good for generic usage, but it lacks one thing: your tools. By leveraging the layered nature of Docker images, you can take my Docker image, add the tools and configuration your team uses, and use that as the image for building SharePoint Framework solutions in your team.

One common scenario I use to illustrate how you can extend the image I built, is by adding a custom .npmrc file with the credentials to your private npm registry. Once you start building SharePoint Framework solutions, you will create more and more reusable components that you most likely won’t publish on npm. Instead, you would use a private registry to host your packages. While you can’t change my image, you can extend it, adding to it your custom .npmrc file along with any other tools your team uses.

Extend the standard SharePoint Framework Docker image

To build a Docker image, all you need is Docker and a yaml file containing instructions for Docker how to build the image.

To illustrate how to extend the Docker image I provided, let’s assume all you wanted to do, is to include a custom .npmrc file with the URL and credentials to your private npm registry.

Start with creating a file named Dockerfile with the following contents:

FROM waldekm/spfx:1.4.1

This one line tells Docker that you want to build a new image based on the SharePoint Framework Docker image I created.

Next to the Dockerfile file, create a new file named .npmrc. In the .npmrc file, paste the URL and credentials you got from your private npm registry. The string would look similar to:

registry=https://contoso.pkgs.visualstudio.com/_packaging/spfx/npm/registry/
always-auth=true

; Treat this auth token like a password. Do not share it with anyone, including Microsoft support. This token expires on or before 6/2/2018.
; begin auth token
//contoso.pkgs.visualstudio.com/_packaging/spfx/npm/registry/:_authToken=eyJ0eXAiOiJKV1...
//contoso.pkgs.visualstudio.com/_packaging/spfx/npm/:_authToken=eyJ0eXAiOiJKV1QiL...
; end auth token

The last thing you have to do, is to instruct Docker to copy this .npmrc file into the image. For this, change the contents of the Dockerfile to:

FROM waldekm/spfx:1.4.1

COPY .npmrc /home/spfx/.npmrc

CMD /bin/bash

That’s it! Build your custom Docker image by executing in the command prompt:

docker build -t contoso-spfx:1.4.1 .

Once Docker built your image, you can start it the same way you would start my image:

docker run -h spfx -it --rm --name ${PWD##*/} -v $PWD:/usr/app/spfx -p 5432:5432 -p 4321:4321 -p 35729:35729 contoso-spfx:1.4.1

Summary

Using Docker images you can efficiently switch between the different versions of the SharePoint Framework. By extending the generic SharePoint Framework Docker image I created, you can get even more out of using Docker in your development process.