Skip to content

Faster contributor setup with the dev container #67440

Open

Description

@Ethan-Arrowood

In 2026 I ran two Node.js Code and Learn events. They went really well, but the main issue at both was getting people set up efficiently. The existing nodejs/devcontainer work helped tremendously: we hit far fewer platform-specific issues. Anyone who has been to a past Code and Learn knows what a headache the various Windows setups were. Though the dev container process isn't perfect. It asks a lot of first-time contributors, and I believe most of that can be avoided. This issue outlines how the devcontainer setup works today, the problems it has, and a roadmap for how I think we can improve it.

This isn't just for first-time contributors either. I prefer to use the devcontainer myself since it has the latest nightly build ready to go for me whenever I want to contribute something. The goal is to improve the contributor setup process overall through optimizing our official devcontainer system.

How it works today

  1. Every night, nodejs/devcontainer builds an image. It contains a shallow clone of main, the Nix toolchain, and a full build in out/. The build alone takes ~2 h 20 min on a 4-core GitHub runner.
  2. Contributors clone their fork and open it in the dev container (.devcontainer/base/devcontainer.json). Their checkout is mounted over the image's copy, and the image's out/ becomes the build cache.
  3. Ninja rebuilds any output that is older than its inputs. A fresh clone stamps every file with the current time, so the whole tree looks changed.
  4. To prevent that, the container runs git restore-mtime, which sets each file's time to its last commit. Files that haven't changed since the image are then older than the cache, and ninja skips them. This is why the docs need a full clone (restore-mtime reads the whole nodejs/node repo history).
  5. direnv loads the toolchain from the checkout's shell.nix. If the checkout's nixpkgs pin differs from the image's, Nix downloads a new toolchain.

Problems

Downloads:

What Size
Full clone of nodejs/node ~1.6 GB (~2.5 GB on disk)
nodejs/devcontainer:nightly ~3.8 GB (10.4 GB unpacked)
Nix toolchain, whenever the checkout's nixpkgs pin differs from the image's (the pin moves weekly) 1.7 GiB (5 GiB unpacked)
Total ~5.4 GB, up to ~7.2 GB, and ~16 GB of disk

First build:

  • Best case, checkout and image at the same commit: 341 s on 6 cores. That is only because the documented ./configure --ninja doesn't match the flags the image was built with. The image's own checkout, with its own flags, has nothing to rebuild.
  • Stale image: this fall the nightly schedule was disabled for inactivity, and the image stayed a month old. A fresh checkout then needed ~3,400 of 4,867 build steps, V8 included, which is nearly a full build.

Silent failures:

  • git restore-mtime fails on "dubious ownership" under Podman, Colima and rootless Docker, and in some shells reports 0 files updated. Either way, the build quietly falls back to compiling everything.
  • restore-mtime uses author dates by default. A commit authored before the image was built but landed after it keeps the cached object, so the binary silently lacks that change.
  • While the image was stale, its prebuilt node couldn't load the newer lib/ from the checkout, and make lint-js broke.

The full history of the repo shouldn't be needed to make most contributions. Neither should hours of compiling.

Goal

Make the dev container the fastest way for anyone to start working on Node.js:

  • Small download: a shallow clone (~120 MB) plus the image, with no toolchain download. That's ~3.9 GB instead of up to ~7.2 GB.
  • Fast first build: about a minute. When I tested a rebuild where every file's time was wrong, but the toolchain and flags matched the image, the ccache already shipped in the image made it finish in 73 s on 6 cores.
  • Not only for first-timers. Existing contributors can pull the latest nightly cache and start a branch from fresh main without rebuilding V8 locally.
  • Not tied to your machine. The heavy build runs in the dev container on any container platform (Docker, Podman, Codespaces, a remote host), while your edits stay in a normal local checkout with your own editor and git.

Plan

Stage 1: build the dev container image from every successful nodejs/node daily build

Stage 2: fast contributor setup

PRs to come; I'll link them here as they open.

  • nodejs/devcontainer: record the image's Node.js commit, and publish an immutable nightly-<sha> tag next to nightly.
  • nodejs/devcontainer: replace git restore-mtime with a manifest of the image's file contents (git blob IDs). A small script gives unchanged files an old timestamp and changed files the current one. It needs no history, so a shallow clone works, and it is correct whether the checkout is ahead of or behind the image.
  • nodejs/devcontainer: load the toolchain from the image's own shell.nix, not the checkout's, so a newer nixpkgs pin doesn't trigger a download and a full rebuild.
  • nodejs/devcontainer: keep the image's checkout-dependent node off PATH, so make lint-js works when the checkout is newer than the image.
  • nodejs/node: have .devcontainer/base/devcontainer.json run the new script, falling back to git restore-mtime on older images.
  • nodejs/node: update doc/contributing/using-devcontainer.md: a shallow clone is enough, and build with the image's flags (./configure $CONFIG_FLAGS).

Later

  • A "no clone" mode that works directly in the image's own checkout, so the download is the image alone.
  • Codespaces support (Figure out and document how to use devcontainer with GitHub codespace devcontainer#19).
  • A smaller image, starting with the benchmark tooling (R, Java) that a build doesn't need.
  • Additional image variants for specific work, built through the existing IMAGE_VARIANT build arg. For example, one with shell.nix's withQuic option for experimental QUIC work.

How you can help

The first blocker is nodejs/devcontainer#31, so reviews there help the most.

A simple 👍 on this issue tells me you're supportive of this effort. Please also comment if you have any ideas or critiques.

Any existing Node.js contributors interested in helping directly, please request to join the nodejs/devcontainer team so I can tag you on necessary PRs!

AI-assisted (Claude Opus 5.5, my setup). The words are my own, per the Human Voice policy.

Activity

  1. added
    buildIssues and PRs related to Node.js builds or CI infrastructure.
    toolsIssues and PRs related to the tools directory.
    on Nov 12, 2026
  2. Ethan-Arrowood commented on Nov 12, 2026

    @Ethan-Arrowood
    ContributorAuthor

    cc @joyeecheung @bnb @aduh95 @targos as the existing contributors to the devcontainer repo

    cc @avivkeller since you've expressed direct interest in this and the Code and Learn stuff for future events and GSOC.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    buildIssues and PRs related to Node.js builds or CI infrastructure.toolsIssues and PRs related to the tools directory.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions