Add an optional compose-based containerized dev environment

[clement-igonet]

Description

Setting up a reproducible three.js dev environment currently depends on the host machine: a matching Node version, a Chromium download for e2e testing (~200 MB, per CONTRIBUTING.md), and OS-specific differences that occasionally surface in screenshot-based e2e results. New contributors pay this cost on their first PR, and CI behavior is not always easy to reproduce locally.

Solution

An optional, documented compose.yml at the repo root (works with both docker compose and podman compose) providing two services:

• dev: Node LTS container running npm ci and npm start, with the repo bind-mounted and port 8080 published, so compose up dev gives the local server from a clean environment.
• test: same image running npm run lint and npm run test-unit (and optionally npm run test-e2e with the browser dependencies preinstalled), matching the CI environment more closely for reproducing failures.

The containers change nothing for contributors who prefer plain npm ci; it is an additive convenience, a few dozen lines plus a short section in CONTRIBUTING.md. I am happy to submit a PR if there is interest.

Alternatives

• A devcontainer.json (VS Code / Codespaces specific; compose is editor-neutral, and a devcontainer can reuse the same compose file later).
• Documenting a plain docker run one-liner in CONTRIBUTING.md (no orchestration of dev vs test, harder to keep in sync).
• Status quo: works, but environment drift between contributors and CI remains a support cost (e.g. e2e screenshot instability across platforms).

Additional context

The e2e README notes the effort spent making screenshots deterministic; a pinned container image removes one more source of variance (fonts, browser build, platform rendering). I am preparing GIS-related example contributions and would use this setup for all testing; other example authors would benefit the same way.

[mrdoob]

This means adding more dependencies, right?

[clement-igonet]

I would say less dependencies to install on local machine if embedded in containers.
As a dev on multi projects, I prefer to keep a clean env between a project to another.
It's a way to clearly define the node version, update, downgrade...
It's also a way to be more reliable from dev to prod.

[mrdoob]

Can you make a step by step list of the process every contributor will have to follow?

[clement-igonet]

Can you make a step by step list of the process every contributor will have to follow?

Sure. One-time requirement: Docker (or Podman). Nothing else to install on the machine, package.json is untouched, and the only new file is the 19 line compose.yml below.

git clone https://github.com/[yourgithubname]/three.js.git
cd three.js

docker compose up -d dev    # dev server at http://localhost:8080, rebuilds on change
docker compose run test     # npm test (lint + unit tests) in a clean container
docker compose down         # stop everything

That is the whole process. Contributors who prefer the current npm ci workflow keep working exactly as today; this is additive.

I verified the flow end to end with this exact file: up -d dev serves the examples (screenshot below), and run test passes lint and the unit test suites, with the ~200 MB Chromium needed by the unit tests living inside the container image instead of on the contributor machine.

compose.yml

services:
  dev:
    image: docker.io/library/node:22-bookworm
    working_dir: /three.js
    volumes:
      - .:/three.js
    ports:
      - "8080:8080"
    command: bash -c "npm ci && npm start"

  test:
    image: ghcr.io/puppeteer/puppeteer:latest
    user: root
    working_dir: /three.js
    volumes:
      - .:/three.js
    command: bash -c "npm ci && npm test"

webgl_geometry_cube served from the dev container:

[mrdoob]

Thanks for explaining 🙏
Can you check if all the e2e tests pass with that setup?

[clement-igonet]

Can you check if all the e2e tests pass with that setup?

Yes, all of them: lint, the unit suites and the 5 e2e shards run green on the branch: https://github.com/clement-igonet/three.js-1/actions/runs/33966210145

One note: the e2e screenshot references are tied to the CI rendering environment, so pixel comparisons are only meaningful in CI. That is already true today and this PR does not change it.

[mrdoob]

One note: the e2e screenshot references are tied to the CI rendering environment, so pixel comparisons are only meaningful in CI. That is already true today and this PR does not change it.

I thought you were replicating the CI rendering environment. Not sure this is needed then.

[clement-igonet]

I thought you were replicating the CI rendering environment. Not sure this is needed then.

The value is the contributor loop rather than e2e: up -d dev and run test (lint + unit) work anywhere with nothing installed on the machine, and that is what contributors run locally today; e2e stays in CI either way, as CONTRIBUTING already states. Happy to drop the e2e service from #34463 and keep the minimal two-service version if you prefer.

[mrdoob]

This is more maintenance work for us.
I'd rather wait a few months to see if more contributors find this valuable.

[clement-igonet]

Fair enough, I converted #34463 to a draft until then; this issue can serve as the reference if more contributors ask for it.

[donmccurdy]

I'm not sure it's worthwhile to maintain a containerized dev environment in the repo... hardware makes a significant difference for three.js E2E and we can't containerize that, unfortunately. As for unit tests — if there were a problem along the lines of "unit tests fail only on windows", then I think it would be easier to have CI run unit tests in both Windows and Linux to keep them in a working state.