Remove lazy discovery from workflow/next

.changeset/remove-next-lazy-discovery.md

@@ -0,0 +1,8 @@
+---
+'@workflow/next': major
+'@workflow/builders': patch
+---
+
+Remove the Next.js lazy discovery/deferred builder path and the `workflows.lazyDiscovery` option.
+
+Fall back to direct generated-file overwrites on Windows when atomic rename is blocked by Next.js dev server file handles.

.github/workflows/event-log-race-repro.yml

@@ -68,7 +68,6 @@ jobs:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       TURBO_TEAM: ${{ vars.TURBO_TEAM }}
       WORKFLOW_PUBLIC_MANIFEST: '1'
-      WORKFLOW_NEXT_LAZY_DISCOVERY: '0'
 
     steps:
       - name: Checkout Repo

.github/workflows/tests.yml

@@ -353,7 +353,6 @@ jobs:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       TURBO_TEAM: ${{ vars.TURBO_TEAM }}
       WORKFLOW_PUBLIC_MANIFEST: '1'
-      WORKFLOW_NEXT_LAZY_DISCOVERY: ${{ matrix.app.canary != true && (matrix.app.name == 'nextjs-turbopack' || matrix.app.name == 'nextjs-webpack') && '0' || '' }}
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -477,7 +476,6 @@ jobs:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       TURBO_TEAM: ${{ vars.TURBO_TEAM }}
       WORKFLOW_PUBLIC_MANIFEST: '1'
-      WORKFLOW_NEXT_LAZY_DISCOVERY: ${{ matrix.app.lazyDiscovery == false && '0' || matrix.app.lazyDiscovery == true && '1' || '' }}
 
     steps:
       - name: Checkout Repo
@@ -561,7 +559,6 @@ jobs:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       TURBO_TEAM: ${{ vars.TURBO_TEAM }}
       WORKFLOW_PUBLIC_MANIFEST: '1'
-      WORKFLOW_NEXT_LAZY_DISCOVERY: ${{ matrix.app.lazyDiscovery == false && '0' || matrix.app.lazyDiscovery == true && '1' || '' }}
 
     steps:
       - name: Checkout Repo
@@ -666,7 +663,6 @@ jobs:
       WORKFLOW_PUBLIC_MANIFEST: '1'
       WORKFLOW_TARGET_WORLD: "@workflow/world-postgres"
       WORKFLOW_POSTGRES_URL: "postgres://world:world@localhost:5432/world"
-      WORKFLOW_NEXT_LAZY_DISCOVERY: ${{ matrix.app.lazyDiscovery == false && '0' || matrix.app.lazyDiscovery == true && '1' || '' }}
 
     steps:
       - name: Checkout Repo
@@ -848,7 +844,11 @@ jobs:
           NODE_OPTIONS: "--enable-source-maps"
           APP_NAME: "nextjs-turbopack"
           DEPLOYMENT_URL: "http://localhost:3000"
-          DEV_TEST_CONFIG: '{"generatedStepPath":"app/.well-known/workflow/v1/flow/__step_registrations.js","generatedWorkflowPath":"app/.well-known/workflow/v1/flow/route.js","apiFilePath":"app/api/chat/route.ts","apiFileImportPath":"../../..","port":3000}'
+          # Use a real workflow file for the Windows HMR test. Most of this
+          # workbench's workflows are symlinks into workbench/example, and
+          # Windows/Turbopack can rebuild from the symlink path while still
+          # serving the previous module contents from the realpath cache.
+          DEV_TEST_CONFIG: '{"generatedStepPath":"app/.well-known/workflow/v1/flow/__step_registrations.js","generatedWorkflowPath":"app/.well-known/workflow/v1/flow/route.js","apiFilePath":"app/api/chat/route.ts","apiFileImportPath":"../../..","port":3000,"testWorkflowFile":"96_many_steps.ts"}'
 
       - name: Print Next.js server logs
         if: always()

docs/content/docs/v4/api-reference/workflow-next/with-workflow.mdx

@@ -68,7 +68,6 @@ const nextConfig: NextConfig = {};
 
 export default withWorkflow(nextConfig, {
   workflows: {
-    lazyDiscovery: true,
     local: {
       port: 4000,
     },
@@ -79,7 +78,6 @@ export default withWorkflow(nextConfig, {
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `workflows.lazyDiscovery` | `boolean` | `false` | When `true`, defers workflow discovery until files are requested instead of scanning eagerly at startup. Useful for large projects where startup time matters. |
 | `workflows.local.port` | `number` | — | Overrides the `PORT` environment variable for local development. Has no effect when deployed to Vercel. |
 | `workflows.sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. See [Source maps](#source-maps) below. |
 

docs/content/docs/v5/api-reference/workflow-next/with-workflow.mdx

@@ -92,7 +92,6 @@ const nextConfig: NextConfig = {};
 
 export default withWorkflow(nextConfig, {
   workflows: {
-    lazyDiscovery: false,
     local: {
       port: 4000,
     },
@@ -103,7 +102,6 @@ export default withWorkflow(nextConfig, {
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `workflows.lazyDiscovery` | `boolean` | `true` | Defers workflow discovery until files are requested instead of scanning eagerly at startup. Set to `false` to force eager discovery (scanning the project up front). Requires a Next.js version that supports deferred entries; older versions fall back to eager discovery automatically. |
 | `workflows.local.port` | `number` | — | Overrides the `PORT` environment variable for local development. Has no effect when deployed to Vercel. |
 | `workflows.sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. See [Source maps](#source-maps) below. |
 

packages/builders/src/base-builder.ts

@@ -1,5 +1,12 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, realpath, rename, writeFile } from 'node:fs/promises';
+import {
+  mkdir,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { promisify } from 'node:util';
@@ -467,6 +474,37 @@ export abstract class BaseBuilder {
     return state;
   }
 
+  /**
+   * Writes generated files atomically where possible. On Windows, Next.js can
+   * briefly hold generated route files open while compiling them, which makes
+   * rename-over-existing fail with EPERM/EACCES. In that case, fall back to a
+   * direct overwrite so watch rebuilds can still make progress.
+   */
+  private async writeGeneratedFile(
+    targetPath: string,
+    content: string
+  ): Promise<void> {
+    const tempPath = `${targetPath}.${randomUUID()}.tmp`;
+    await writeFile(tempPath, content);
+    try {
+      await rename(tempPath, targetPath);
+    } catch (error) {
+      const errorCode =
+        error && typeof error === 'object' && 'code' in error
+          ? (error as NodeJS.ErrnoException).code
+          : undefined;
+      if (
+        process.platform === 'win32' &&
+        (errorCode === 'EPERM' || errorCode === 'EACCES')
+      ) {
+        await writeFile(targetPath, content);
+        await rm(tempPath, { force: true });
+        return;
+      }
+      throw error;
+    }
+  }
+
   /**
    * Writes debug information to a JSON file for troubleshooting build issues.
    * Uses atomic write (temp file + rename) to prevent race conditions when
@@ -504,12 +542,7 @@ export abstract class BaseBuilder {
         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);
+      await this.writeGeneratedFile(targetPath, mergedData);
     } catch (error: unknown) {
       console.warn('Failed to write debug file:', error);
     }
@@ -1213,11 +1246,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
           const outputDir = dirname(outfile);
           await mkdir(outputDir, { recursive: true });
 
-          // 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);
+          await this.writeGeneratedFile(outfile, workflowFunctionCode);
           return;
         }
 
@@ -1396,10 +1425,7 @@ const workflowCode = \`${escapedVMCode}\`;
 export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
 
     if (!bundleFinalOutput) {
-      // Write directly (Next.js will bundle)
-      const tempPath = `${flowOutfile}.${randomUUID()}.tmp`;
-      await writeFile(tempPath, combinedFunctionCode);
-      await rename(tempPath, flowOutfile);
+      await this.writeGeneratedFile(flowOutfile, combinedFunctionCode);
     } else {
       // Bundle the combined code for standalone use
       const bundleStartTime = Date.now();
@@ -1469,9 +1495,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 
       const outputDir = dirname(flowOutfile);
       await mkdir(outputDir, { recursive: true });
-      const tempPath = `${flowOutfile}.${randomUUID()}.tmp`;
-      await writeFile(tempPath, code);
-      await rename(tempPath, flowOutfile);
+      await this.writeGeneratedFile(flowOutfile, code);
     };
 
     if (this.config.watch) {