Standardize VS Code Toolchains with a Single devcontainer.json

The problem: toolchain drift

A new teammate clones the repository, runs npm install, and hits a lint error that no one else sees. The cause is rarely the code; it is the environment. Node versions differ, global ESLint installs drift, and editor extensions are personal choices. A .devcontainer/devcontainer.json file solves this by defining the entire development environment—base image, extensions, forwarded ports, and setup commands—inside the repository. When you open the folder in VS Code, the editor builds a Docker container from that definition and connects to it. Your CI pipeline can consume the same file, so local and remote environments stop diverging.

The mechanism: one JSON file, two environments

Dev Containers rely on Docker (or a compatible container runtime) to isolate the toolchain. The workspace directory is bind-mounted into the container, so file edits persist on the host filesystem, but compilers, language servers, and package managers run inside the container. VS Code installs a matching server component inside the container and forwards the UI from your local client. Extensions declared in the configuration are installed inside the container, not on the host, which keeps linters and formatters consistent.

A minimal devcontainer.json

Place the following file at .devcontainer/devcontainer.json:

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  },
  "forwardPorts": [3000],
  "postCreateCommand": "npm ci"
}

Each field controls a specific part of the environment:

• image selects the base container. Pin to a specific tag such as :20 rather than latest; unpinned tags can change under you and break builds.
• features adds versioned, reusable add-ons from an OCI registry. The example installs the GitHub CLI without maintaining a custom Dockerfile.
• customizations.vscode.extensions lists extensions to install inside the container. They appear in the Extensions view with a badge indicating they are installed in the Dev Container.
• forwardPorts publishes container ports to localhost on your machine. Port 3000 becomes reachable at http://localhost:3000.
• postCreateCommand runs once after the container is created. npm ci installs dependencies exactly as pinned in package-lock.json.

What happens when you reopen the folder

After you add the file, VS Code detects it and prompts Reopen in Container. Accepting the prompt triggers a build and start sequence: Docker pulls the base image, applies features, creates the container, bind-mounts your workspace, starts the VS Code Server, installs the declared extensions, and runs postCreateCommand. The integrated terminal then opens inside the container, usually as a non-root user (vscode or node) that has sudo access for occasional administrative tasks.

Running the same config in CI

The Dev Container CLI (devcontainer) can build and run the identical configuration outside VS Code. From the repository root, run:

devcontainer up --workspace-folder .

This command requires the devcontainer CLI to be installed and Docker to be running. It builds the environment and leaves it ready for subsequent build or test commands. If the command fails, the logs usually point to a missing base image, a feature that cannot be resolved, or a postCreateCommand that exits non-zero. In GitHub Actions or GitLab CI, the same command replaces ad-hoc setup scripts, so the Node version and installed extensions match what developers use locally.

Limits and common mistakes

Bind-mount performance

On macOS and Windows, the workspace bind-mount goes through a virtualization layer. Heavy I/O workloads—such as node_modules installation or large build outputs—can feel slower than native disk access. A common mitigation is to keep those paths on a Docker volume instead of the bind-mount by adding a mounts entry with "type": "volume".

Host-dependent extensions and credentials

Extensions that expect host-level binaries—for example, SSH key agents or GPU-accelerated tools—may not function inside the container without extra forwarding. Git credentials are a frequent friction point: the host credential manager is not automatically visible. Mounting the host .gitconfig into the container, or configuring a credential helper inside it, restores expected behavior.

Permissions and image size

The default non-root user may lack permission to install certain system packages. You can temporarily set "remoteUser": "root" for setup steps, or use a custom Dockerfile that switches to USER root, performs installation, and then returns to the non-root user. Large base images increase pull and startup time; prefer slim variants and clean package manager caches in postCreateCommand or a Dockerfile.

VS Code Server version mismatch

The VS Code Server installed inside the container must match the client version. After a client update, an already-running container may report that the server failed to start. Rebuilding the container from the command palette resolves the mismatch.

How to verify the container is working

Open the integrated terminal inside the container and run node --version. The output should match the tag in the image field (for example, a v20.x release for typescript-node:20). In the Extensions view, confirm that ESLint and Prettier show as installed in the Dev Container. To test port forwarding, start a development server inside the container—npm run dev is a typical script—and open http://localhost:3000 on the host.

From a host terminal, inspect the running container:

docker exec -it <container-id> id

This confirms the active user and group. To check mounts, run:

docker inspect <container-id> | jq '.[0].Mounts'

You should see the workspace bind-mount and any named volumes you configured. Replace <container-id> with the actual ID from docker ps.

When one container is not enough

The minimal example assumes a single container. If your application needs a database or cache, reference a docker-compose.yml from devcontainer.json using dockerComposeFile and service. This keeps the application container identical to the single-container case while adding sibling services for local development.