Description

The marigold-docs build on Vercel is intermittently SIGKILLed with out_of_memory during Turbopack's compile step. It started with the Vite 8.3.2 → 8.3.3 bump (#5980) and blocks the "Version Packages" release PR, because Vercel – marigold-docs is a required status check.

This PR lowers the build's peak memory instead of reverting any dependency. On Vercel preview and production builds only, Turbopack's webpack loaders (mostly the fumadocs-mdx MDX compile) now run in worker threads instead of a pool of separate Node child processes:

turbopackPluginRuntimeStrategy: ['preview', 'production'].includes(process.env.VERCEL_ENV)
  ? 'forceWorkerThreads'
  : undefined,

Local runs (pnpm dev, pnpm build, vercel dev) keep Next's default. The investigation below is kept in full so it can be reused the next time the docs build runs out of memory.

Closes DST-1904

Root cause

The docs build has been running close to the 8 GB limit of Vercel's standard build machine (4 cores, 8 GB), and its peak memory swings by about 1 GB between runs of identical code. The Vite bump didn't break anything; it tipped a borderline build over the edge.

Evidence from Vercel:

• The OOM always happens inside next build → "Creating an optimized production build" (Turbopack compile), about 50s in. Green builds on the same machine compile in 26s–58s, so the compile phase itself is highly variable.
• Same tree, different outcome. The chore(deps): bump vite from 8.3.2 to 8.3.3 #5980 PR head e0b2e7e has a tree byte-identical to the failing main commit 62da88a (git diff --stat e0b2e7e 62da88a is empty) and built green.
• Clear onset. In the ~5 weeks of failed docs builds before the bump there was no OOM (failures were ERR_PNPM_OUTDATED_LOCKFILE, git_info_fail or plain build errors). Since Vite 8.3.3 landed, 5 of 8 docs builds containing it were OOM-killed:

The last good production deployment is dpl_DWb7szA6ukAdc5pLFs66gHXeEgSL (f8441c2); the live docs stay on it until this is fixed.

What the bump changed for the docs build. The diff only touches vite in the root and packages/cli manifests plus a lockfile dedupe. The one change inside the docs importer is that fumadocs-mdx is re-resolved against new peers (rolldown 1.2.11 → 1.2.13, vite 8.3.2 → 8.3.3). The fumadocs-mdx webpack loader that Next uses does not import Vite or Rolldown; only its dist/vite and rolldown adapters do. So there is no direct mechanism. The bump shifted a noisy distribution just enough.

Where the memory goes

A snapshot of the next build process tree at its compile peak (local, macOS):

More than half the peak is the pool of Node child processes that run JS loaders, each with its own Node runtime and heap. Across runs the pool grew to 35–51 processes on an 8-core machine. That pool is what this PR targets.

What was measured

Method. Local runs on macOS (16 GB, 8 cores, Node 24.11.0) in detached worktrees. Peak = maximum of the summed RSS of the next build process tree, sampled every 0.5s. "Compile peak" stops at Compiled successfully. Summed RSS counts shared pages once per process, so it overstates the child-process setup and the absolute numbers don't map 1:1 to Vercel's Linux container. Treat them as relative comparisons. The run-to-run noise is about ±1 GB, so every variant ran 2–3 times.

1. Cold A/B: last green commit vs. failing commit

Possibly slightly higher, but within noise. This matches "borderline build tipped over", not "regression".

2. Turbopack build cache (experimental.turbopackFileSystemCacheForBuild, default true in 16.4.2): ruled out

Simulates Vercel exactly: f8441c2 was built in place, then 62da88a was checked out at the same path and built on top of that cache.

Disabling the cache doesn't lower the peak. Side finding worth a separate look: a cache restored from a build under a different lockfile makes the compile about 2.5× slower than a cold build. Vercel restores the previous deployment's cache on every build, so dependency-bump builds pay this. Not a memory problem, but it costs build minutes.

Pitfall for anyone repeating this: the Turbopack cache stores absolute paths (for example fumadocs-mdx's .source/source.config.mjs). A cache copied to a different directory fails with "webpack loader path … is outside configured roots". Always test cache scenarios at the same path. Vercel always builds at /vercel/path0, so this is not an issue there.

3. Capping Turbopack's Rust thread pools: ruled out

Both names are compiled into the @next/swc binary, but Next configures its runtimes explicitly. The thread count doesn't change, so the env vars have no effect.

4. Loader runtime: child processes vs. worker threads (this PR)

experimental.turbopackPluginRuntimeStrategy, added in Next 16.4.0, documented in node_modules/next/dist/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackPluginRuntimeStrategy.md.

About 0.5 GB (~13%) lower on average, consistently lower in each pair, all builds green, build time unchanged. Because summed RSS overcounts child processes, the real saving on Vercel is probably somewhat smaller. That's why this PR also turns on Vercel's build system report (see Rollout).

Options checked and not available

• Turbopack memory limit: no such option in Next 16.4.2 (memoryLimit doesn't appear in config-schema.js).
• experimental.turbopackMemoryEviction: documented as "only effective in dev sessions".
• experimental.turbopackGc: prunes unreachable tasks from the persistent cache, which doesn't lower the peak.
• Webpack loader pool size: not configurable.
• experimental.cpus / staticGenerationMaxConcurrency: these only affect static page generation, which runs after the compile step where the OOM happens.

Why forceWorkerThreads, and why only on Vercel builds

On Node >= 24.13.1, Next ignores 'workerThreads', prints a warning and falls back to child processes (next/dist/server/config.js). That guards against nodejs/node#65100: the process can abort when a worker thread exits while a native addon holds a live Node-API threadsafe function. Vercel's 24.x is newer than 24.13.1, so 'forceWorkerThreads' is the only way to get worker threads there.

The trigger Next names is fsevents, the macOS file watcher. Vercel builds on Linux, where fsevents isn't installed and next build doesn't watch files. On developer Macs, fsevents is installed and .node-version pins only 24, so a teammate on the latest Node 24 would be exposed. Hence the scoping:

Verified locally by loading the config through next/dist/server/config with each VERCEL_ENV value.

Both Vercel projects build the docs

Both run pnpm build in docs/ with the same next.config.mjs, so this change covers both: marigold-production builds with VERCEL_ENV=production. It hasn't failed yet only because its last build (dpl_6z9aSsoQwrzPQTdBNhyzdDF91gBd, Oct 12, compile 55s) predates the Vite bump. The first build after the next release would have been the first one at risk, and a failure there would keep the live site on the old version.

Rollout and validation

• VERCEL_BUILD_SYSTEM_REPORT=1 is now set on both projects: marigold-docs (production + preview, env id lG9sMyZmUQh7oBlx) and marigold-production (production; its previews never build). Vercel's own OOM message recommends it. Every build log now ends with a build system report, so we get the real memory numbers from the Linux container instead of macOS estimates. It's a diagnostic setting and can be removed once things are stable.
• The failure is intermittent (about 5 in 8), so a single green preview proves nothing. Merge only after 3–5 preview builds in a row succeed.
• If a preview build aborts instead of running out of memory (a crash at worker teardown rather than SIGKILL), we've hit worker_threads Worker exit aborts (SIGABRT) when a native addon (fsevents) has an in-flight napi_threadsafe_function — napi_release_threadsafe_function / uv_mutex_lock nodejs/node#65100 on Linux after all. Revert this PR.
• If OOMs continue with worker threads, the remaining option that keeps all dependency updates is Enhanced Builds for marigold-docs (16 GB build machine, paid).

Test Instructions

1. Open this PR's marigold-docs Vercel build log. In the next build header, the experiments list should show turbopackPluginRuntimeStrategy: "workerThreads" along with Next's warning that 'forceWorkerThreads' bypasses the Node.js guard. The log should end with the "Build system report".
2. Redeploy the preview 3–5 times (Vercel UI → Redeploy, or vercel redeploy <preview-url> --scope marigold). Every build must finish, and the report shows the peak memory.
3. Locally: cd docs && pnpm build. The experiments list must not show turbopackPluginRuntimeStrategy, because local builds keep Next's default.
4. Optional: check the config resolution without building:

   cd docs
   for e in "" development preview production; do
     VERCEL_ENV=$e node -e "require('next/dist/server/config').default('phase-production-build', process.cwd()).then(c => console.log('VERCEL_ENV=${e:-unset} ->', c.experimental.turbopackPluginRuntimeStrategy))"
   done

   Expected: unset and development → childProcesses, preview and production → workerThreads.

Breaking Changes

No

Checklist

• Storybook preview and Marigold docs preview are available
• Stories added/updated (with component-test tag where applicable)
• Unit tests added/updated
• Component documentation added/updated (if it exists)
• Accessibility reviewed against ARIA APG (for new/changed interactive components)
• Visual regression tests updated (for UI changes)
• Changeset added (pnpm changeset)

N/A for this PR: stories, unit tests, component docs, accessibility, VRT and changeset. It's a build-config change to the private @marigold/docs package, with no published package and no UI change. The docs preview item is left for the reviewer, since it depends on the Vercel builds above.