Repository navigation
Description
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
- Every night,
nodejs/devcontainerbuilds an image. It contains a shallow clone ofmain, the Nix toolchain, and a full build inout/. The build alone takes ~2 h 20 min on a 4-core GitHub runner. - 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'sout/becomes the build cache. - 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.
- 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-mtimereads the wholenodejs/noderepo history). - 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 --ninjadoesn'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-mtimefails on "dubious ownership" under Podman, Colima and rootless Docker, and in some shells reports0 files updated. Either way, the build quietly falls back to compiling everything.restore-mtimeuses 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
nodecouldn't load the newerlib/from the checkout, andmake lint-jsbroke.
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
mainwithout 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
- Add building by specific commit SHA devcontainer#31: build a given Node.js commit, triggered by
nodejs/node's daily workflow, with a weekly fallback and a keepalive, so the schedule can't silently stop again. - build: trigger devcontainer build from daily #67153: after the daily build succeeds, send its commit to
nodejs/devcontainerusing arepository_dispatchevent. - Give nodejs-github-bot write access on
nodejs/devcontainerso the dispatch works.
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 immutablenightly-<sha>tag next tonightly. -
nodejs/devcontainer: replacegit restore-mtimewith 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 ownshell.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-dependentnodeoffPATH, somake lint-jsworks when the checkout is newer than the image. -
nodejs/node: have.devcontainer/base/devcontainer.jsonrun the new script, falling back togit restore-mtimeon older images. -
nodejs/node: updatedoc/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_VARIANTbuild arg. For example, one withshell.nix'swithQuicoption 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
Ethan-Arrowood commentedon Nov 12, 2026
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.