bug(adapter/cloudflare): turborepo terminates the process in midway when using `workerd` as prerender environment

[kumardeo]

Astro Info

Astro                    v6.1.8
Node                     v22.21.1
System                   Linux (x64)
Package Manager          pnpm
Output                   static
Adapter                  @astrojs/cloudflare
Integrations             @astrojs/mdx
                         @astrojs/react
                         @astrojs/partytown
                         @vite-pwa/astro-integration

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

When migrating an astro app from 5 to 6 in turborepo, it behaves in a strange way when using cloudflare adapter and workerd as prerender environment.

My astro app is located at apps/web

When the build command is run in apps/web directory, it builds the app as expected.
Example:
(from root)
cd apps/web
pnpm run build

Logs:

✓ built in 269ms
21:36:22 [build] Server built in 33.83s
21:36:22 [build] Complete!

But, when the build command is run by turbo, it exits without fully building the app (mostly when prerendering phase begins) and no error at all.
Example:
(from root)
turbo run build

Logs:

web:build: 
21:28:31 [assets] Copying fonts (16 files)...
web:build: Using secrets defined in .env
web:build: 21:28:32 [vite] ✓ built in 9.50s
21:28:37 [WARN] [vite] src/pages/ssr-test/index.astro (25:18): "components" is not exported by "src/pages/ssr-test/_content.mdx", imported by "src/pages/ssr-test/index.astro".
web:build: Using secrets defined in .env
:sparkles: Parsed 2 valid header rules. (x2)

 Tasks:    5 successful, 5 total
Cached:    2 cached, 5 total
  Time:    41.713s

Observations:

Turbo terminates the process as soon as prerendering begins in workerd prerender environment, it does not terminate when prerenderEnvironment: 'node' is used in cloudflare adapter config.

I am not sure, but looks like when workerd environment is used, it does not block properly and turbo thinks execution is completed so terminates the process.

What's the expected result?

The app should build completely with workerd prerender environment when build command is run by turborepo.

Link to Minimal Reproducible Example

https://github.com/kumardeo/astro-repro-16396

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

• Reproduced: Skipped — no minimal reproduction was provided and the issue requires a Turborepo monorepo setup with Cloudflare Workers to reproduce.
• Exploration: Partial
• Priority: P2: has workaround. This only affects users running Astro with the Cloudflare adapter's default workerd prerender environment inside a Turborepo monorepo. The workaround is straightforward: set prerenderEnvironment: 'node' in the Cloudflare adapter config.

When prerenderEnvironment: 'workerd' (the default) is used, the Cloudflare adapter's prerenderer (packages/integrations/cloudflare/src/prerenderer.ts) spins up a Vite preview server backed by Miniflare, which spawns a workerd child process via child_process.spawn() with 4 piped stdio streams (["pipe", "pipe", "pipe", "pipe"]). This child process is part of the same process group as the parent Node.js process and is not detached or unref'd. Turborepo monitors its task processes via process groups and stdio pipes — when the main build output stops flowing but the process group remains alive (due to the lingering workerd child process and Vite preview server HTTP server), Turborepo likely interprets this as the task completing and terminates the process group, killing the build mid-prerender. With prerenderEnvironment: 'node', no child process or extra server is created — everything happens in-process — so Turborepo correctly detects task completion.

I wasn't able to find a fix, but I identified some areas that may be relevant. The interaction is between Turborepo's process lifecycle management and Miniflare's workerd child process spawning (miniflare dist/src/index.js around line 63541). The exit-hook registered by Miniflare (line 81357) calls void this.#runtime?.dispose() in a synchronous process.on('exit') handler, meaning it fire-and-forgets the async disposal — cleanup may not complete before the process exits. Potential fixes could involve: (1) ensuring the Astro build process doesn't appear "idle" to Turborepo while prerendering is active (e.g., periodic heartbeat output), or (2) investigating whether Turborepo has configuration options for process group handling (e.g., persistent task configuration). As a workaround, setting prerenderEnvironment: 'node' in the adapter config avoids the issue entirely. This may also be worth reporting upstream to Turborepo since the behavior of killing a process group that still has active child processes is arguably a Turborepo concern.

Full Triage Report

Investigation Summary

No report.md was available; this analysis was conducted by exploring the codebase directly.

Code Path Analysis

Workerd prerender lifecycle:

1. During astro:build:start, the Cloudflare adapter registers a custom prerenderer via setPrerenderer() (packages/integrations/cloudflare/src/index.ts:399-412).

2. prerenderer.setup() (packages/integrations/cloudflare/src/prerenderer.ts:52-96) creates a Vite preview server with @cloudflare/vite-plugin, which internally creates a Miniflare instance that spawns a workerd child process.

3. The workerd process is spawned at miniflare dist/src/index.js:63541:

   const runtimeProcess = child_process.spawn(command, args, {
     stdio: ["pipe", "pipe", "pipe", "pipe"],
     env: { ...process.env, FORCE_COLOR: FORCE_COLOR2 }
   });

   • Not detached, not .unref()'d — stays in same process group
   • 4 piped stdio streams (stdin, stdout, stderr, control pipe on fd 3)

4. All prerendering happens via HTTP requests to the preview server → Miniflare → workerd (prerenderer.ts:130-137).

5. Teardown (prerenderer.ts:177-183) calls previewServer.close(), which calls miniflare.dispose(), which calls runtime.dispose() (line 63607-63622) — this sends SIGKILL to the workerd process and awaits its exit.

Why prerenderEnvironment: 'node' works:

With 'node', no custom prerenderer is set — Astro uses its default createDefaultPrerenderer() (packages/astro/src/core/build/default-prerenderer.ts), which imports the prerender entry bundle and calls BuildApp.render() directly in-process. No child processes, no extra servers, no lingering pipes.

Miniflare exit-hook (line 81357-81365):

this.#removeExitHook = exitHook(() => {
  void this.#runtime?.dispose();  // fire-and-forget async!
  // ...sync cleanup...
});

The exit-hook library handles SIGTERM by calling callbacks synchronously then calling process.exit(128 + 15). The void keyword means dispose() (which is async) is not awaited — the workerd SIGKILL may not complete before the process exits.

Turborepo Interaction Theory

Turborepo likely considers a task "complete" when the main process's stdout/stderr pipes close or when output stops flowing. With the workerd prerender environment:

• The Vite preview server and workerd child process keep the Node event loop alive
• Main build output may pause during prerendering (which happens via HTTP, not stdout)
• Turborepo interprets this silence as task completion and sends SIGTERM/SIGKILL to the process group
• The build is terminated mid-prerender

Workaround

Set prerenderEnvironment: 'node' in the Cloudflare adapter configuration:

// astro.config.mjs
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    prerenderEnvironment: 'node',
  }),
});

Potentially Relevant Files

• packages/integrations/cloudflare/src/prerenderer.ts — Cloudflare prerenderer implementation
• packages/integrations/cloudflare/src/index.ts — Adapter integration entry, lines 399-412
• packages/astro/src/core/build/generate.ts — Build generation pipeline, prerenderer lifecycle
• packages/astro/src/core/build/default-prerenderer.ts — Default (node) prerenderer for comparison
• Miniflare dist/src/index.js lines 63533-63622 — Runtime class, workerd process management
• Miniflare dist/src/index.js lines 81350-81365 — Exit hook registration

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

[kumardeo]

Steps to reproduce the issue:

1. Clone repo:

   git clone https://github.com/kumardeo/astro-repro-16396

2. Install dependencies:

   pnpm install

3. Run build command from root:

   pnpm run build
   

[matthewp]

@astrobot-houston try again

[astrobot-houston]

• Reproduced: Skipped — the workerd prerender environment does not function in our CI sandbox. All attempts to run astro build with the Cloudflare adapter's workerd prerender environment resulted in connect ECONNREFUSED errors. The Cloudflare adapter's own workerd-based prerender tests also fail with the same error in this environment, confirming an environment-level incompatibility.
• Exploration: Partial
• Priority: P2: Has Workaround. This only affects users running the Cloudflare adapter with the default workerd prerender environment inside a Turborepo monorepo. Setting prerenderEnvironment: 'node' in the adapter config avoids the issue entirely. Direct builds (outside Turborepo) work fine.

When prerenderEnvironment: 'workerd' (the default) is used, the Cloudflare adapter's prerenderer (packages/integrations/cloudflare/src/prerenderer.ts) creates a Vite preview server backed by Miniflare, which spawns a workerd child process with stdio: ["pipe", "pipe", "pipe", "pipe"]. This child process is NOT detached and NOT .unref()'d — it stays in the same process group as the parent Node.js process. Turborepo monitors task processes via process groups and stdio pipes; when main build output pauses during prerendering (which happens via HTTP requests, not stdout), Turborepo likely interprets this as the task completing and terminates the process group. With prerenderEnvironment: 'node', everything runs in-process with no child processes or extra servers, so Turborepo correctly detects completion.

I wasn't able to find a fix, but I identified some areas that may be relevant. The interaction is between Turborepo's process lifecycle management and Miniflare's workerd child process spawning. Potential avenues include: (1) ensuring the Astro build keeps producing output during prerendering (heartbeat), (2) investigating Turborepo's persistent task configuration, or (3) reporting upstream to Turborepo since killing a process group with active child processes is arguably a Turborepo concern. As a workaround, set prerenderEnvironment: 'node' in the adapter config:

adapter: cloudflare({
  prerenderEnvironment: 'node',
})

Full Triage Report

Investigation Summary

Reproduction: Skipped (host-specific)

The workerd prerender environment does not function in the CI sandbox. All attempts to run astro build with the Cloudflare adapter's workerd prerender environment resulted in connect ECONNREFUSED errors when the build tried to fetch from the Vite preview server backed by workerd/Miniflare. The Cloudflare adapter's own test suite confirms this — all workerd-based prerender tests fail with the same ECONNREFUSED error.

What Was Attempted

1. Cloned the reproduction repo (kumardeo/astro-repro-16396) — a Turborepo monorepo with an Astro app using @astrojs/cloudflare adapter with prerenderEnvironment: "workerd" and output: "server".

2. Installed dependencies — all dependencies including workerd binary installed successfully. The workerd binary runs and responds correctly.

3. Tested Miniflare directly — Miniflare works correctly in isolation (can create workers and dispatch fetch requests).

4. Attempted direct build — Failed with connect ECONNREFUSED 127.0.0.1:<random_port> during the prerendering phase.

5. Set up monorepo-integrated reproduction — Same ECONNREFUSED error with the local workspace's @astrojs/cloudflare adapter.

6. Ran the Cloudflare adapter's own test suite — All workerd-related prerender tests fail with ECONNREFUSED, confirming environment-level incompatibility.

Code Path Analysis

Workerd prerender lifecycle:

1. During astro:build:start, the Cloudflare adapter registers a custom prerenderer via setPrerenderer() (packages/integrations/cloudflare/src/index.ts:~399-412).

2. prerenderer.setup() (packages/integrations/cloudflare/src/prerenderer.ts:52-96) creates a Vite preview server with @cloudflare/vite-plugin, which internally creates a Miniflare instance that spawns a workerd child process.

3. The workerd process is spawned with stdio: ["pipe", "pipe", "pipe", "pipe"] — not detached, not .unref()'d — stays in the same process group as the parent Node.js process.

4. All prerendering happens via HTTP requests to the preview server → Miniflare → workerd (prerenderer.ts:130-137).

5. Teardown (prerenderer.ts:177-183) calls previewServer.close() → miniflare.dispose() → runtime.dispose() — this sends SIGKILL to the workerd process and awaits its exit.

Why prerenderEnvironment: 'node' works: No custom prerenderer is set — Astro uses its default createDefaultPrerenderer() (packages/astro/src/core/build/default-prerenderer.ts), which runs everything in-process. No child processes, no extra servers, no lingering pipes.

Potentially Relevant Files

• packages/integrations/cloudflare/src/prerenderer.ts — Cloudflare workerd prerenderer implementation
• packages/integrations/cloudflare/src/index.ts — Adapter integration entry
• packages/astro/src/core/build/generate.ts — Build generation pipeline, prerenderer lifecycle
• packages/astro/src/core/build/default-prerenderer.ts — Default (node) prerenderer for comparison

Notes for Future Investigation

• This may be a Turborepo issue rather than an Astro issue, since the build works when run directly
• Turborepo's persistent: true task option might be relevant — though it's typically for dev servers, not build tasks
• The fix might involve ensuring the Astro build process keeps producing output during prerendering, or properly managing the workerd child process's stdio pipes
• It could also be worth investigating whether the @cloudflare/vite-plugin's preview server properly blocks until the workerd backend is fully initialized

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.