tracking: Re-upgrade to Astro 7 once @astrojs/compiler-binding pnpm resolution is fixed upstream #26

New Issue

2026-08-26T18:33:53Z

Ninosaurier commented

2026-08-26 18:33:53 +00:00

Context

We downgraded from Astro 7 → 6.3.x in #23 due to an upstream bug in @astrojs/compiler-binding's optional-dependency resolution under pnpm (native platform binary never installed, only pnpm install --force worked as a non-viable workaround).

What needs to happen before re-upgrading

[x ] Upstream issue withastro/astro is closed/resolved
[x ] Verify fix actually resolves it in a fresh pnpm workspace (don't just trust the changelog — reproduce our original repro steps from #23)
[x ] Re-add astro@^7.x and @astrojs/starlight@^0.41.x (or whatever the current versions are by then)
[x ] Re-add @astrojs/compiler-binding handling in pnpm-workspace.yaml if still needed (allowBuilds, hoist patterns — see what we removed in #25 for reference)
[x ] Full pnpm install + pnpm run docs test on both Linux and macOS before merging

## Context We downgraded from Astro 7 → 6.3.x in #23 due to an upstream bug in `@astrojs/compiler-binding`'s optional-dependency resolution under pnpm (native platform binary never installed, only `pnpm install --force` worked as a non-viable workaround). ## What needs to happen before re-upgrading - [x ] Upstream issue withastro/astro is closed/resolved - [x ] Verify fix actually resolves it in a fresh pnpm workspace (don't just trust the changelog — reproduce our original repro steps from #23) - [x ] Re-add `astro@^7.x` and `@astrojs/starlight@^0.41.x` (or whatever the current versions are by then) - [x ] Re-add `@astrojs/compiler-binding` handling in `pnpm-workspace.yaml` if still needed (`allowBuilds`, hoist patterns — see what we removed in #25 for reference) - [x ] Full `pnpm install` + `pnpm run docs` test on both Linux and macOS before merging ## Related - #23 (original bug) - #25 (downgrade fix)

Ninosaurier added the Kind/Enhancement Priority/Low Status/Blocked labels 2026-08-26 18:33:53 +00:00

Ninosaurier self-assigned this 2026-08-26 18:33:53 +00:00

Ninosaurier commented

2026-08-28 10:52:25 +00:00

Follow-up: root cause not conclusively identified — extensive testing inconclusive

Wanted to document this honestly rather than leave a false trail for future readers.

After the initial downgrade workaround (#23), we tried to pin down the exact root cause more precisely, since the issue seemed to reappear intermittently even with the newer Astro/pnpm versions that initially looked like a fix. Several package.json variations were suspected as the trigger at different points, most recently the devEngines.runtime node version constraint (>=22.0.0 vs >=24.0.0).

Testing performed: 7+ isolated, clean-environment installs (full node_modules + pnpm store wipe each time) comparing:

Original vs. regenerated (pnpm init) root package.json
With/without devEngines.runtime

=22.0.0 vs >=24.0.0 node version constraints
pnpm 11.11.0 vs 11.24.0
Astro pinned to the exact originally-affected version (7.2.4) vs. latest

Result: None of these variables reproduced the failure deterministically in a clean container. Every combination tested installed @astrojs/compiler-binding-linux-x64-gnu successfully. This strongly suggests the package.json content itself is not the actual cause — the earlier local reproductions were most likely influenced by something environment-specific (registry timing/latency, local store state, background processes) rather than a deterministic config trigger.

Current status: Working reliably on the latest Astro 7 / pnpm versions. We're treating this as resolved in practice, without a fully confirmed root cause. If it resurfaces, the next step would be a --loglevel debug diff between a failing and a succeeding install on the same machine with an unchanged package.json, to get an objective (not inferred) answer.

Leaving this here so nobody re-chases the devEngines.runtime theory as a confirmed cause — it didn't hold up under isolated testing.

Follow-up: root cause not conclusively identified — extensive testing inconclusive Wanted to document this honestly rather than leave a false trail for future readers. After the initial downgrade workaround (#23), we tried to pin down the exact root cause more precisely, since the issue seemed to reappear intermittently even with the newer Astro/pnpm versions that initially looked like a fix. Several package.json variations were suspected as the trigger at different points, most recently the devEngines.runtime node version constraint (>=22.0.0 vs >=24.0.0). Testing performed: 7+ isolated, clean-environment installs (full node_modules + pnpm store wipe each time) comparing: Original vs. regenerated (pnpm init) root package.json With/without devEngines.runtime >=22.0.0 vs >=24.0.0 node version constraints pnpm 11.11.0 vs 11.24.0 Astro pinned to the exact originally-affected version (7.2.4) vs. latest Result: None of these variables reproduced the failure deterministically in a clean container. Every combination tested installed @astrojs/compiler-binding-linux-x64-gnu successfully. This strongly suggests the package.json content itself is not the actual cause — the earlier local reproductions were most likely influenced by something environment-specific (registry timing/latency, local store state, background processes) rather than a deterministic config trigger. Current status: Working reliably on the latest Astro 7 / pnpm versions. We're treating this as resolved in practice, without a fully confirmed root cause. If it resurfaces, the next step would be a --loglevel debug diff between a failing and a succeeding install on the same machine with an unchanged package.json, to get an objective (not inferred) answer. Leaving this here so nobody re-chases the devEngines.runtime theory as a confirmed cause — it didn't hold up under isolated testing.

Ninosaurier added Status/Needs Review and removed Status/Blocked labels 2026-08-28 10:52:55 +00:00

Ninosaurier added reference fix/#26-re-upgrade-to-astro-7

2026-08-28 13:02:56 +00:00

Ninosaurier commented

2026-08-28 13:09:16 +00:00