spfx-container

Purpose

Containerized SharePoint Framework (SPFx) development using Docker + WSL2, with a Dev Container for VS Code.

Project setup

• Dockerfile builds a Node 22 image with pnpm and runs the SPFx dev server.
• docker-compose.yml wires ports, volumes, and environment for local dev.
• .devcontainer/devcontainer.json uses the compose file so VS Code can attach a full dev environment.

Prerequisites (Windows + WSL2)

• Windows 11/10 with WSL2 enabled.
• Docker Desktop with WSL2 integration enabled for your distro.
• VS Code with the "Dev Containers" extension.

Optional but recommended:

• Git in WSL.
• Node tooling on the host only if you want to run outside containers.

WSL2 + Docker workflow

Recommended layout:

1. Clone the repo inside your WSL2 filesystem (e.g. ~/code/spfx-container).
2. Open that folder in VS Code using the WSL extension (Remote - WSL).
3. Reopen in container when prompted (or run "Dev Containers: Reopen in Container").

Why: bind mounts are faster and more reliable when the source is inside WSL rather than on C:\.

Dev Container usage

This repo is set up for VS Code Dev Containers:

• .devcontainer/devcontainer.json points to docker-compose.yml.
• The container exposes:
  • 4321 (SPFx dev server)
  • 35729 (live reload)
• The container mounts the workspace and a node_modules volume to avoid Windows/WSL conflicts.

To start:

1. Open the repo in VS Code (from WSL path).
2. Run "Dev Containers: Reopen in Container".
3. In the container terminal:
   • npm install
   • npm run start

Dockerfile details

Dockerfile:

• Base image: node:22
• Installs pnpm globally.
• Copies package.json (install step is optional).
• Copies the repo.
• Exposes 4321 and 35729.
• Runs npm run start by default.

If you want deterministic installs, add a pnpm-lock.yaml and update the Dockerfile to copy it and run pnpm i --frozen-lockfile.

docker-compose details

docker-compose.yml:

• Builds the image from Dockerfile.
• Maps ports 4321 and 35729.
• Mounts:
  • Workspace to /usr/app
  • Anonymous volume for /usr/app/node_modules
  • ${USERPROFILE}/.gcb to /root/.gcb for SPFx dev certs (adjust if needed)
• Sets NODE_ENV=development.

To run manually without VS Code:

docker compose up --build

Then open:

• https://localhost:4321 (SPFx dev server)

Common WSL2 issues

• Slow or broken bind mounts: move the repo into WSL (/home/<user>/...), not C:\.
• Docker Compose validation errors: ensure docker-compose.yml has build only for build options, and image/ports/volumes/env at the service level.
• Missing .gcb directory: run SPFx cert setup in the container or adjust the mount to your cert location.

Minimal Path to Awesome

From the dev container:

npm install
npm run start

References

• https://aka.ms/spfx
• https://learn.microsoft.com/sharepoint/dev/spfx/set-up-your-developer-tenant