Skip to content

The only tool you need to know what is happening and how to fix it.

ci: give Node one source of truth, and move it to 26 (#346)

FrameAutomata96e6284b9049
diff --git a/.github/workflows/benchmark-processor.yml b/.github/workflows/benchmark-processor.yml
index 8b787990..212dad55 100644
--- a/.github/workflows/benchmark-processor.yml
+++ b/.github/workflows/benchmark-processor.yml
@@ -85,7 +85,7 @@ jobs:
- uses: dtolnay/rust-toolchain@stable
- uses: actions/setup-node@v7
with:
- node-version: 22
+ node-version-file: .nvmrc
- name: Build oxc shim
run: bash scripts/build-oxc-shim.sh
- name: Build traceway collector (oxc)
diff --git a/.github/workflows/release-docs.yml b/.github/workflows/release-docs.yml
index 1fae2c7d..6cf77d8a 100644
--- a/.github/workflows/release-docs.yml
+++ b/.github/workflows/release-docs.yml
@@ -18,7 +18,7 @@ jobs:
- name: Setup Node
uses: actions/setup-node@v7
with:
- node-version: "latest"
+ node-version-file: .nvmrc
cache: "npm"
cache-dependency-path: docs/package-lock.json
diff --git a/.github/workflows/release-traceway.yml b/.github/workflows/release-traceway.yml
index 0a67ce86..51c3ad96 100644
--- a/.github/workflows/release-traceway.yml
+++ b/.github/workflows/release-traceway.yml
@@ -62,9 +62,9 @@ jobs:
- name: Setup Node
uses: actions/setup-node@v7
with:
- # frontend/package.json only declares a floor (>=22); keep the
- # release build on the same major the Dockerfiles use.
- node-version: 22
+ # .nvmrc is the repo-wide Node pin, shared with the Dockerfiles
+ # NODE_VERSION build arg and the nix dev shells.
+ node-version-file: .nvmrc
cache: "npm"
cache-dependency-path: frontend/package-lock.json
@@ -209,6 +209,15 @@ jobs:
- name: Checkout
uses: actions/checkout@v7
+ # One --build-arg read from .nvmrc, so every image below is built on the
+ # same Node major as CI and the dev shells rather than on whatever each
+ # Dockerfile's ARG default happens to say.
+ - name: Read the Node pin
+ id: node
+ run: |
+ ./scripts/check-node-pins.sh
+ echo "version=$(cat .nvmrc)" >> "$GITHUB_OUTPUT"
+
- name: Set up QEMU
uses: docker/setup-qemu-action@v4
@@ -228,6 +237,8 @@ jobs:
with:
context: .
file: ./Dockerfile
+ build-args: |
+ NODE_VERSION=${{ steps.node.outputs.version }}
push: true
tags: |
ghcr.io/${{ github.repository_owner }}/traceway:v${{ inputs.version }}
@@ -241,6 +252,8 @@ jobs:
with:
context: .
file: ./Dockerfile.minimal
+ build-args: |
+ NODE_VERSION=${{ steps.node.outputs.version }}
push: true
tags: |
ghcr.io/${{ github.repository_owner }}/traceway:v${{ inputs.version }}-minimal
@@ -254,6 +267,8 @@ jobs:
with:
context: .
file: ./Dockerfile.sqlite
+ build-args: |
+ NODE_VERSION=${{ steps.node.outputs.version }}
platforms: linux/amd64,linux/arm64
push: true
tags: |
@@ -271,6 +286,8 @@ jobs:
with:
context: .
file: ./Dockerfile.duckdb
+ build-args: |
+ NODE_VERSION=${{ steps.node.outputs.version }}
platforms: linux/amd64
push: true
tags: |
@@ -288,6 +305,8 @@ jobs:
with:
context: .
file: ./Dockerfile.browser
+ build-args: |
+ NODE_VERSION=${{ steps.node.outputs.version }}
platforms: linux/amd64
push: true
tags: |
diff --git a/.github/workflows/release-website.yml b/.github/workflows/release-website.yml
index c1e9d666..219406cb 100644
--- a/.github/workflows/release-website.yml
+++ b/.github/workflows/release-website.yml
@@ -18,7 +18,7 @@ jobs:
- name: Setup Node
uses: actions/setup-node@v7
with:
- node-version: "latest"
+ node-version-file: .nvmrc
cache: "npm"
cache-dependency-path: website/package-lock.json
diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 00000000..6f4247a6
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+26
diff --git a/CLAUDE.md b/CLAUDE.md
index 5c9c2705..a9d57417 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -33,7 +33,10 @@ Traceway is an error tracking and monitoring platform consisting of:
| CLI | `cd cli && just test` | Runs unit tests |
| CLI | `cd cli && just check` | Lint + test + vulncheck + skill drift + contract tests (pre-commit gate; CI enforces it for `cli/`) |
| CLI | `cd cli && just smoke-test` | Live E2E (needs `TRACEWAY_SMOKE_*` env vars) |
-| Any | `nix develop` (or direnv via `.envrc`) | Dev shell with the Go and Node versions read from `backend/go.mod` and `frontend/package.json`, plus `just`, `golangci-lint`, `govulncheck` (`flake.nix`; shells `default`, `backend`, `frontend`, `oxc`). Put `JWT_SECRET` in the gitignored `.envrc.local` |
+| Any | `nix develop` (or direnv via `.envrc`) | Dev shell with the Go and Node versions read from `backend/go.mod` and `.nvmrc`, plus `just`, `golangci-lint`, `govulncheck` (`flake.nix`; shells `default`, `backend`, `frontend`, `oxc`). Put `JWT_SECRET` in the gitignored `.envrc.local` |
+| Any | `./scripts/check-node-pins.sh` | Asserts every Dockerfile's `ARG NODE_VERSION` default matches `.nvmrc`; run by `release-traceway.yml` before it builds |
+
+**Node's version lives in `.nvmrc`** (a bare major, currently `26`) and nothing else derives it independently: every `setup-node` step uses `node-version-file: .nvmrc`, `flake.nix` reads it for the dev shells, and `release-traceway.yml` passes it to all five image builds as `--build-arg NODE_VERSION`. The Dockerfiles each carry an `ARG NODE_VERSION=<major>` default because a bare `docker build` cannot read `.nvmrc`; that default is the one value that can drift, which is what `scripts/check-node-pins.sh` exists to catch (it also fails on a literal `node:<major>` tag reintroduced in a `FROM`). To move Node, edit `.nvmrc` and the ARG defaults, then run the script. `frontend/package.json`'s `engines.node` is deliberately left as a floor (`>=22`) rather than a pin — it is what npm enforces on consumers, and `node-version-file` pointed at it resolves a range to the *newest* release, which is the drift `f95424cc` was fixing. `testing/devtesting-nestjs/Dockerfile` is out of scope: it pins the runtime of a sample third-party app, not anything Traceway builds.
Set `JWT_SECRET` (min 32 characters) before running the backend — it is the one variable with no default in the standalone binary (the all-in-one Docker image bakes a public one in via `backend/.env.docker`, which must be overridden in production). `SQLITE_PATH` sets the database location, defaulting to `./traceway.db` in the working directory.
diff --git a/Dockerfile b/Dockerfile
index 16ae3132..17c78e9b 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -7,7 +7,13 @@
# ==============================================================================
# Stage 1: Build Frontend
# ==============================================================================
-FROM node:22-alpine AS frontend-builder
+# NODE_VERSION must match .nvmrc, the repo-wide Node pin. release-traceway.yml
+# passes it as a --build-arg read from that file, so a released image cannot be
+# built on a different major from CI; the default below is what a bare
+# `docker build` gets.
+ARG NODE_VERSION=26
+
+FROM node:${NODE_VERSION}-alpine AS frontend-builder
WORKDIR /app/frontend
diff --git a/Dockerfile.browser b/Dockerfile.browser
index fd0bd180..eba79d6e 100644
--- a/Dockerfile.browser
+++ b/Dockerfile.browser
@@ -15,7 +15,13 @@
# ==============================================================================
# Stage 1: Build Frontend
# ==============================================================================
-FROM --platform=$BUILDPLATFORM node:22-alpine AS frontend-builder
+# NODE_VERSION must match .nvmrc, the repo-wide Node pin. release-traceway.yml
+# passes it as a --build-arg read from that file, so a released image cannot be
+# built on a different major from CI; the default below is what a bare
+# `docker build` gets.
+ARG NODE_VERSION=26
+
+FROM --platform=$BUILDPLATFORM node:${NODE_VERSION}-alpine AS frontend-builder
WORKDIR /app/frontend
@@ -54,7 +60,7 @@ RUN CGO_ENABLED=1 go build -tags telemetry_duckdb -ldflags="-s -w" -o /traceway
# Stage 3: Playwright harness (pinned @playwright/test + Chromium download).
# npm only exists here; the runtime invokes node against the CLI directly.
# ==============================================================================
-FROM node:22-bookworm-slim AS playwright-builder
+FROM node:${NODE_VERSION}-bookworm-slim AS playwright-builder
WORKDIR /opt/traceway-playwright
diff --git a/Dockerfile.duckdb b/Dockerfile.duckdb
index 4278d4c7..c178d907 100644
--- a/Dockerfile.duckdb
+++ b/Dockerfile.duckdb
@@ -11,7 +11,13 @@
# ==============================================================================
# Stage 1: Build Frontend
# ==============================================================================
-FROM --platform=$BUILDPLATFORM node:22-alpine AS frontend-builder
+# NODE_VERSION must match .nvmrc, the repo-wide Node pin. release-traceway.yml
+# passes it as a --build-arg read from that file, so a released image cannot be
+# built on a different major from CI; the default below is what a bare
+# `docker build` gets.
+ARG NODE_VERSION=26
+
+FROM --platform=$BUILDPLATFORM node:${NODE_VERSION}-alpine AS frontend-builder
WORKDIR /app/frontend
diff --git a/Dockerfile.minimal b/Dockerfile.minimal
index 710fbc00..857dd77c 100644
--- a/Dockerfile.minimal
+++ b/Dockerfile.minimal
@@ -8,7 +8,13 @@
# ==============================================================================
# Stage 1: Build Frontend
# ==============================================================================
-FROM node:22-alpine AS frontend-builder
+# NODE_VERSION must match .nvmrc, the repo-wide Node pin. release-traceway.yml
+# passes it as a --build-arg read from that file, so a released image cannot be
+# built on a different major from CI; the default below is what a bare
+# `docker build` gets.
+ARG NODE_VERSION=26
+
+FROM node:${NODE_VERSION}-alpine AS frontend-builder
WORKDIR /app/frontend
diff --git a/Dockerfile.sqlite b/Dockerfile.sqlite
index 5a9a3577..4b925a8f 100644
--- a/Dockerfile.sqlite
+++ b/Dockerfile.sqlite
@@ -7,7 +7,13 @@
# ==============================================================================
# Stage 1: Build Frontend
# ==============================================================================
-FROM --platform=$BUILDPLATFORM node:22-alpine AS frontend-builder
+# NODE_VERSION must match .nvmrc, the repo-wide Node pin. release-traceway.yml
+# passes it as a --build-arg read from that file, so a released image cannot be
+# built on a different major from CI; the default below is what a bare
+# `docker build` gets.
+ARG NODE_VERSION=26
+
+FROM --platform=$BUILDPLATFORM node:${NODE_VERSION}-alpine AS frontend-builder
WORKDIR /app/frontend
diff --git a/flake.nix b/flake.nix
index 4a5f4a87..b2027c9b 100644
--- a/flake.nix
+++ b/flake.nix
@@ -24,9 +24,11 @@
goVersion = if goToolchain != null then goToolchain else goFloor;
go = pkgs."go_${builtins.elemAt goVersion 0}_${builtins.elemAt goVersion 1}";
- frontendPackage = builtins.fromJSON (builtins.readFile ./frontend/package.json);
- # engines.node is a floor such as ">=22"; the dev shell pins that major.
- nodeMajor = builtins.head (builtins.match "[^0-9]*([0-9]+).*" frontendPackage.engines.node);
+ # .nvmrc is the single source of truth for Node's major, shared with every
+ # setup-node step and the Dockerfiles' NODE_VERSION build arg. Read from
+ # there rather than from engines.node, which is a floor (">=22") and so
+ # names the oldest supported major, not the one to build with.
+ nodeMajor = builtins.head (builtins.match "[[:space:]]*v?([0-9]+).*" (builtins.readFile ./.nvmrc));
nodejs = pkgs."nodejs_${nodeMajor}";
goTools = [
diff --git a/scripts/check-node-pins.sh b/scripts/check-node-pins.sh
new file mode 100755
index 00000000..c1dc6764
--- /dev/null
+++ b/scripts/check-node-pins.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Every Node version in this repo is derived from .nvmrc: the setup-node steps
+# and flake.nix read it directly, and release-traceway.yml passes it to the
+# Docker builds as NODE_VERSION. The Dockerfiles still carry an ARG default,
+# because a bare `docker build` has no way to read .nvmrc -- so that default is
+# the one value that can drift. This asserts it has not.
+#
+# Deliberately not checked: testing/devtesting-nestjs/Dockerfile, which pins the
+# runtime of a sample third-party app rather than anything Traceway builds.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+pinned=$(tr -d '[:space:]v' < .nvmrc)
+if [[ ! $pinned =~ ^[0-9]+$ ]]; then
+ echo "check-node-pins: .nvmrc must hold a bare Node major, got '$pinned'" >&2
+ exit 1
+fi
+
+status=0
+for f in Dockerfile Dockerfile.minimal Dockerfile.sqlite Dockerfile.duckdb Dockerfile.browser; do
+ found=$(sed -n 's/^ARG NODE_VERSION=\([0-9]*\).*/\1/p' "$f")
+ if [[ -z $found ]]; then
+ echo "check-node-pins: $f has no 'ARG NODE_VERSION=' default" >&2
+ status=1
+ elif [[ $found != "$pinned" ]]; then
+ echo "check-node-pins: $f pins Node $found, .nvmrc says $pinned" >&2
+ status=1
+ fi
+done
+
+# A literal node: tag left behind would silently ignore both .nvmrc and the ARG.
+if literal=$(grep -rnE '^FROM .*node:[0-9]' Dockerfile Dockerfile.minimal Dockerfile.sqlite Dockerfile.duckdb Dockerfile.browser); then
+ echo "check-node-pins: hardcoded node tag, use \${NODE_VERSION}:" >&2
+ echo "$literal" >&2
+ status=1
+fi
+
+[[ $status -eq 0 ]] && echo "check-node-pins: all Dockerfiles agree with .nvmrc ($pinned)"
+exit $status