fix: nitro build race conditions

.changeset/fifty-teeth-grin.md

@@ -0,0 +1,7 @@
+---
+"@workflow/sveltekit": patch
+"@workflow/builders": patch
+"@workflow/nitro": patch
+---
+
+Fix Nitro and SvelteKit build race conditions and make writing debug file atomic

packages/builders/src/base-builder.ts

@@ -1,4 +1,5 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 import { promisify } from 'node:util';
 import chalk from 'chalk';
@@ -176,31 +177,46 @@ export abstract class BaseBuilder {
 
   /**
    * Writes debug information to a JSON file for troubleshooting build issues.
-   * Executes whenever called, regardless of environment variables.
+   * Uses atomic write (temp file + rename) to prevent race conditions when
+   * multiple builds run concurrently.
    */
   private async writeDebugFile(
     outfile: string,
     debugData: object,
     merge?: boolean
   ): Promise<void> {
+    const targetPath = `${outfile}.debug.json`;
+    let existing = {};
+
     try {
-      let existing = {};
       if (merge) {
-        existing = JSON.parse(
-          await readFile(`${outfile}.debug.json`, 'utf8').catch(() => '{}')
-        );
+        try {
+          const content = await readFile(targetPath, 'utf8');
+          existing = JSON.parse(content);
+        } catch (e) {
+          // File doesn't exist yet or is corrupted - start fresh.
+          // Don't log error for ENOENT (file not found) as that's expected on first run.
+          if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {
+            console.warn('Error reading debug file, starting fresh:', e);
+          }
+        }
       }
-      await writeFile(
-        `${outfile}.debug.json`,
-        JSON.stringify(
-          {
-            ...existing,
-            ...debugData,
-          },
-          null,
-          2
-        )
+
+      const mergedData = JSON.stringify(
+        {
+          ...existing,
+          ...debugData,
+        },
+        null,
+        2
       );
+
+      // Write atomically: write to temp file, then rename.
+      // rename() is atomic on POSIX systems and provides best-effort atomicity on Windows.
+      // Prevents race conditions where concurrent builds read partially-written files.
+      const tempPath = `${targetPath}.${randomUUID()}.tmp`;
+      await writeFile(tempPath, mergedData);
+      await rename(tempPath, targetPath);
     } catch (error: unknown) {
       console.warn('Failed to write debug file:', error);
     }
@@ -561,7 +577,11 @@ export const POST = workflowEntrypoint(workflowCode);`;
         const outputDir = dirname(outfile);
         await mkdir(outputDir, { recursive: true });
 
-        await writeFile(outfile, workflowFunctionCode);
+        // Atomic write: write to temp file then rename to prevent
+        // file watchers from reading partial file during write
+        const tempPath = `${outfile}.${randomUUID()}.tmp`;
+        await writeFile(tempPath, workflowFunctionCode);
+        await rename(tempPath, outfile);
         return;
       }
 

packages/builders/src/build-queue.ts

@@ -0,0 +1,26 @@
+/**
+ * Creates a build queue that serializes async tasks to prevent race conditions.
+ *
+ * When rapid file changes trigger multiple builds, this ensures they run
+ * sequentially rather than concurrently, avoiding issues like:
+ * - Partial file reads during writes
+ * - Corrupted merge operations
+ * - Duplicate/conflicting builds
+ *
+ * @example
+ * const enqueue = createBuildQueue();
+ *
+ * // These will run sequentially, not concurrently
+ * enqueue(() => builder.build());
+ * enqueue(() => builder.build());
+ */
+export function createBuildQueue() {
+  let queue = Promise.resolve();
+
+  return (task: () => Promise<void>): Promise<void> => {
+    queue = queue.then(task).catch((err) => {
+      console.error(err);
+    });
+    return queue;
+  };
+}

packages/builders/src/index.ts

@@ -15,8 +15,6 @@ export type {
   VercelBuildOutputConfig,
   WorkflowConfig,
 } from './types.js';
-export {
-  isValidBuildTarget,
-  validBuildTargets,
-} from './types.js';
+export { isValidBuildTarget, validBuildTargets } from './types.js';
 export { VercelBuildOutputAPIBuilder } from './vercel-build-output-api.js';
+export { createBuildQueue } from './build-queue.js';

packages/nitro/src/vite.ts

@@ -6,9 +6,11 @@ import type { Plugin as VitePlugin } from 'vite';
 import type { ModuleOptions } from './index.js';
 import nitroModule from './index.js';
 import { workflowTransformPlugin } from '@workflow/rollup';
+import { createBuildQueue } from '@workflow/builders';
 
 export function workflow(options?: ModuleOptions): Plugin[] {
-  let builder: LocalBuilder | undefined;
+  let builder: LocalBuilder;
+  const enqueue = createBuildQueue();
 
   return [
     workflowTransformPlugin() as VitePlugin,
@@ -28,7 +30,7 @@ export function workflow(options?: ModuleOptions): Plugin[] {
         },
       },
       // NOTE: This is a workaround because Nitro passes the 404 requests to the dev server to handle.
-      //       For workflow routes, we override to send an empty body to prevent Hono/Vite's SPA fallback.
+      // For workflow routes, we override to send an empty body to prevent Hono/Vite's SPA fallback.
       configureServer(server) {
         // Add middleware to intercept 404s on workflow routes before Vite's SPA fallback
         return () => {
@@ -44,7 +46,7 @@ export function workflow(options?: ModuleOptions): Plugin[] {
               const statusCode = typeof args[0] === 'number' ? args[0] : 200;
 
               // NOTE: Workaround because Nitro passes 404 requests to the vite to handle.
-              //       Causes `webhook route with invalid token` test to fail.
+              // Causes `webhook route with invalid token` test to fail.
               // For 404s on workflow routes, ensure we're sending the right headers
               if (statusCode === 404) {
                 // Set content-length to 0 to prevent Vite from overriding
@@ -61,7 +63,7 @@ export function workflow(options?: ModuleOptions): Plugin[] {
       },
       // TODO: Move this to @workflow/vite or something since this is vite specific
       async hotUpdate(options: HotUpdateOptions) {
-        const { file, server, read } = options;
+        const { file, read } = options;
 
         // Check if this is a TS/JS file that might contain workflow directives
         const jsTsRegex = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
@@ -75,15 +77,8 @@ export function workflow(options?: ModuleOptions): Plugin[] {
           content = await read();
         } catch {
           // File might have been deleted - trigger rebuild to update generated routes
-          console.log('Workflow file deleted, rebuilding...');
-          if (builder) {
-            await builder.build();
-          }
-          // NOTE: Might be too aggressive
-          server.ws.send({
-            type: 'full-reload',
-            path: '*',
-          });
+          console.log('Workflow file changed, rebuilding...');
+          await enqueue(() => builder.build());
           return;
         }
 
@@ -97,17 +92,8 @@ export function workflow(options?: ModuleOptions): Plugin[] {
           return;
         }
 
-        // Trigger full reload - this will cause Nitro's dev:reload hook to fire,
-        // which will rebuild workflows and update routes
         console.log('Workflow file changed, rebuilding...');
-        if (builder) {
-          await builder.build();
-        }
-        server.ws.send({
-          type: 'full-reload',
-          path: '*',
-        });
-
+        await enqueue(() => builder.build());
         // Let Vite handle the normal HMR for the changed file
         return;
       },

packages/sveltekit/src/plugin.ts

@@ -1,22 +1,23 @@
 import type { HotUpdateOptions, Plugin } from 'vite';
 import { SvelteKitBuilder } from './builder.js';
 import { workflowTransformPlugin } from '@workflow/rollup';
+import { createBuildQueue } from '@workflow/builders';
 
 export function workflowPlugin(): Plugin[] {
   let builder: SvelteKitBuilder;
+  const enqueue = createBuildQueue();
 
   return [
     workflowTransformPlugin(),
     {
       name: 'workflow:sveltekit',
-
       configResolved() {
         builder = new SvelteKitBuilder();
       },
 
       // TODO: Move this to @workflow/vite or something since this is vite specific
       async hotUpdate(options: HotUpdateOptions) {
-        const { file, server, read } = options;
+        const { file, read } = options;
 
         // Check if this is a TS/JS file that might contain workflow directives
         const jsTsRegex = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
@@ -30,14 +31,8 @@ export function workflowPlugin(): Plugin[] {
           content = await read();
         } catch {
           // File might have been deleted - trigger rebuild to update generated routes
-          console.log('Workflow file deleted, regenerating routes...');
-          try {
-            await builder.build();
-          } catch (buildError) {
-            // Build might fail if files are being deleted during test cleanup
-            // Log but don't crash - the next successful change will trigger a rebuild
-            console.error('Build failed during file deletion:', buildError);
-          }
+          console.log('Workflow file changed, rebuilding...');
+          await enqueue(() => builder.build());
           return;
         }
 
@@ -51,23 +46,8 @@ export function workflowPlugin(): Plugin[] {
           return;
         }
 
-        // Rebuild everything - simpler and more reliable than tracking individual files
-        console.log('Workflow file changed, regenerating routes...');
-        try {
-          await builder.build();
-        } catch (buildError) {
-          // Build might fail if files are being modified/deleted during test cleanup
-          // Log but don't crash - the next successful change will trigger a rebuild
-          console.error('Build failed during HMR:', buildError);
-          return;
-        }
-
-        // Trigger full reload of workflow routes
-        server.ws.send({
-          type: 'full-reload',
-          path: '*',
-        });
-
+        console.log('Workflow file changed, rebuilding...');
+        await enqueue(() => builder.build());
         // Let Vite handle the normal HMR for the changed file
         return;
       },