Opening a sample using a development container

The Visual Studio Code Remote - Containers extension lets you use a Docker container as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code's full feature set. This container can be used to run an application or to separate tools, libraries, or runtimes needed for working with various versions of SPFx, running on different versions of Node.js.

Workspace files are mounted from the local file system or copied or cloned into the container. Extensions are installed and run inside the container, where they have full access to the tools, platform, and file system. This means that you can seamlessly switch your entire SPFx development environment just by connecting to a different container.

Follow these instructions to configure and run samples using dev containers.

Pre-requisites

Before you can open your first dev container, you'll need to install the pre-requisites on your workstation. To do so, follow these steps:

1. Install and configure Docker for your operating system.

   Windows / macOS:

   1. Install Docker Desktop for Windows/Mac.

   2. If you are using WSL 2 on Windows, to ensure the WSL 2 back-end is enabled: Right-click on the Docker taskbar item and select Settings. Check Use the WSL 2 based engine and verify your distribution is enabled under Resources > WSL Integration.

   3. When not using the WSL 2 back-end, right-click on the Docker task bar item, select Settings and update Resources > File Sharing with any locations your source code is kept. See tips and tricks for troubleshooting.

   Linux:

   1. Follow the official install instructions for Docker CE/EE for your distribution. If you are using Docker Compose, follow the Docker Compose directions as well.

   2. Add your user to the docker group by using a terminal to run: sudo usermod -aG docker $USER

   3. Sign out and back in again so your changes take effect.

2. Install Visual Studio Code or Visual Studio Code Insiders.

3. Install the Remote Development extension pack.

Opening a sample

To open a sample which is container-enabled, use the following steps:

1. Open the solution from the root folder of the solution (the folder containing the package.json) using Visual Studio Code
2. If the Remote Containers extension is installed, you will be prompted to Reopen in Container. If you do not automatically get prompted, use the command palette (F1) and select Remote Containers: Reopen in Container
3. Visual Studio Code will re-open, but the solution name should be appended with [Dev Container:, followed with the name of the dev container require for your solution's SPFx version.
4. The container will pre-install all the required solution dependencies automatically (aka npm install). It will also generate a development certificate to enable using gulp serve to debug the solution. For more information on how to debug a solution running within a container, see Debugging with containers

Debugging with containers

When debugging, the SharePoint Framework communicates from your browser to your local workstation using three ports: 4321, 35729 and -- with SPFx prior to 1.12.1 -- 5432.

The ports are used to load your web part's manifest, handle live reloading, and running the local workbench (if used).

For security reasons, all communications from your browser to your local workstation use TLS, with a self-signed certificate. This is the certificate that SPFx generates and installs for you when running gulp trust-dev-cert the first time you configure your development workstation, and it is unique to your workstation.

When debugging within a remote container, that same debugging traffic is routed from your local workstation to the matching ports on your remote container. Thin is configured with all the sample remote containers via the devcontainer.json with the following settings:

	// Use 'forwardPorts' to make a list of ports inside the container available locally.
	"forwardPorts": [
		4321,
		35729
	],
	"portsAttributes": {
		"4321": {
			"protocol": "https",
			"label": "Manifest",
			"onAutoForward": "silent",
			"requireLocalPort": true
		},
		// Not needed for SPFx>= 1.12.1 
		// "5432": {
		// 	"protocol": "https",
		// 	"label": "Workbench",
		// 	"onAutoForward": "silent"
		// },
		"35729": {
			"protocol": "https",
			"label": "LiveReload",
			"onAutoForward": "silent",
			"requireLocalPort": true
		}
	},

However, the TLS certificate for your local workstation does not match the remote container's workstation, which prevents your browser from trusting the connection and causes it to block the debugging traffic.

To solve this, every sample container in this repository will generate a container-specific certificate when building the container.

This produces both a .cer and a .pem file (depending on your operating system), which you can deploy in your local workstation. Unlike gulp trust-dev-cert, however, it does not automatically install them on your local workstation.

To install the certificates on your local workstation, follow these instructions:

Installing dev certificates locally on a Windows device

Note: These instructions are only necessary the first time you open a remote container based on a new image. It is possible that the certificates for one container will be valid for another container built on the same image. When in doubt, repeat these steps with new container images if necessary.

The .cer and .pem files will automatically be added to the root of the solution. They may appear greyed out in VS Code's file explorer because they are automatically flagged to not be stored in GitHub.

1. Using VS Code within the remote container, select the spfx-dev-cert.cer file and download the file using Download... in the context menu.

   

2. Using the command prompt in your local workstation (i.e. outside of VS Code) change your current directory to where you downloaded the .cer file and run the following command:

   certutil -user -addstore root spfx-dev-cert.cer
   

   Or, if you prefer to use PowerShell:

   Import-Certificate -FilePath "spfx-dev-cert.cer" -CertStoreLocation Cert:\LocalMachine\Root

3. You will get a message indicating that the certificate was successfully installed

Wanted: Instruction for non-windows devices

Error: gulp serve not running

You installed the dev certificate for the remote container to your local workstation, ran gulp serve --nobrowser and still get the following message:

Your web part will not appear in the toolbox. Please make sure "gulp serve" is running in a web part project. Please refresh the page once "gulp serve" is running.

This is most likely because your browser is doing its job and trying to protect you against evil scripts, because it isn't quite sure about your new certificate (after all, your certificate is supposed to be for localhost, but this isn't quite the localhost it was looking for).

You can confirm this behavior by reloading your workbench page while using the Network tab in your browser's dev tools (CTRL+SHIFT-I or F11) and looking for manifest.js in the Name column (there should be a few instances as your browser may try to load it multiple times); it should have (failed) under Status, and will most likely be highlighted in red.

To solve this issue using Chrome or Edge Chromium, follow these steps:

1. From the Network tab in your browser dev tools, select Open in new tab in the context-menu of the manifest.js file -- or navigate to https://localhost:4321/temp/manifests.js in a separate tab.

2. In the new tab, you should see that your browser is currently unhappy with you. The tab title will show Privacy error, the certificate area in the address bar should show Not secure, the address bar should highlight that you're connecting over an invalid https connection, and you should get a message on the page saying Your connection isn't private -- at least, that's what should happen in Edge; your browser may choose to express its paranoia differently.

   

3. If you're certain that you trust the origin of the local manifest (and if your corporate security policies allow you to do so), you may select Advanced on the page. It should display more information about this issue

   

4. Again, if you trust the connection to your own workstation and your corporate policies allow you to do this, you may select Continue to localhost (unsafe)

5. Your browser will (begrudgingly) reload the page and display the manifest. It will still tell you that the content is not secure.

   

6. You may return to the tab where your workbench is displayed and refresh the page. This time, the page should load, albeit with a Not secure message.

   

Tip: You may want to add a browser shortcut to https://localhost:4321/temp/manifests.js to easily repeat these steps as your browser may revert to blocking the page with new sessions.