[next] make lazyDiscovery the default in withWorkflow

.changeset/lazy-discovery-default.md

@@ -0,0 +1,10 @@
+---
+'@workflow/next': minor
+---
+
+Change `lazyDiscovery` default to `true` for `withWorkflow`. Workflow
+discovery is now deferred until files are requested instead of scanning
+eagerly at startup on Next.js versions that support deferred entries
+(>= 16.2.0-canary.48). Older versions automatically fall back to eager
+discovery. Pass `workflows: { lazyDiscovery: false }` to opt back into
+eager discovery on supported Next.js versions.

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

@@ -59,7 +59,7 @@ const nextConfig: NextConfig = {};
 
 export default withWorkflow(nextConfig, {
   workflows: {
-    lazyDiscovery: true,
+    lazyDiscovery: false,
     local: {
       port: 4000,
     },
@@ -69,7 +69,7 @@ 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.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. |
 
 <Callout type="info">

packages/core/e2e/local-build.test.ts

@@ -87,8 +87,7 @@ const DEFERRED_BUILD_MODE_PROJECTS = new Set([
   'nextjs-webpack',
   'nextjs-turbopack',
 ]);
-const DEFERRED_BUILD_UNSUPPORTED_WARNING =
-  'Enabled lazyDiscovery but Next.js version is not compatible';
+const DEFERRED_BUILD_UNSUPPORTED_WARNING = 'lazyDiscovery requires Next.js >=';
 const EAGER_DISCOVERY_LOG = 'Discovering workflow directives';
 
 describe.each([

packages/next/src/builder.ts

@@ -22,7 +22,7 @@ export function shouldUseDeferredBuilder(nextVersion: string): boolean {
   if (flagEnabled && !versionCompatible && !warnedAboutFlagAndVersion) {
     warnedAboutFlagAndVersion = true;
     console.warn(
-      `Enabled lazyDiscovery but Next.js version is not compatible, needs ${DEFERRED_BUILDER_MIN_VERSION} have ${nextVersion}`
+      `lazyDiscovery requires Next.js >= ${DEFERRED_BUILDER_MIN_VERSION} (found ${nextVersion}); falling back to eager workflow discovery.`
     );
   }
 

packages/next/src/index.test.ts

@@ -109,4 +109,22 @@ describe('withWorkflow outputFileTracingRoot', () => {
       workingDir: process.cwd(),
     });
   });
+
+  it('enables lazyDiscovery by default', async () => {
+    withWorkflow({});
+    expect(process.env.WORKFLOW_NEXT_LAZY_DISCOVERY).toBe('1');
+  });
+
+  it('enables lazyDiscovery when explicitly set to true', async () => {
+    withWorkflow({}, { workflows: { lazyDiscovery: true } });
+    expect(process.env.WORKFLOW_NEXT_LAZY_DISCOVERY).toBe('1');
+  });
+
+  it('disables lazyDiscovery when explicitly set to false', async () => {
+    // Ensure env var is set (as if a prior call enabled it) so we can verify
+    // the explicit `false` clears it.
+    process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = '1';
+    withWorkflow({}, { workflows: { lazyDiscovery: false } });
+    expect(process.env.WORKFLOW_NEXT_LAZY_DISCOVERY).toBeUndefined();
+  });
 });

packages/next/src/index.ts

@@ -61,7 +61,12 @@ export function withWorkflow(
     };
   } = {}
 ) {
-  if (workflows?.lazyDiscovery) {
+  // lazyDiscovery defaults to true; pass `lazyDiscovery: false` to force eager
+  // discovery (scanning the project at startup) instead of deferring workflow
+  // discovery until files are requested.
+  if (workflows?.lazyDiscovery === false) {
+    delete process.env.WORKFLOW_NEXT_LAZY_DISCOVERY;
+  } else {
     process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = '1';
   }
 

workbench/nextjs-turbopack/next.config.ts

@@ -1,5 +1,5 @@
-import type { NextConfig } from 'next';
 import path from 'node:path';
+import type { NextConfig } from 'next';
 import { withWorkflow } from 'workflow/next';
 
 const turbopackRoot = path.resolve(process.cwd(), '../..');
@@ -14,7 +14,4 @@ const nextConfig: NextConfig = {
   },
 };
 
-// export default nextConfig;
-export default withWorkflow(nextConfig, {
-  workflows: { lazyDiscovery: true },
-});
+export default withWorkflow(nextConfig);

workbench/nextjs-webpack/next.config.ts

@@ -10,5 +10,4 @@ const nextConfig: NextConfig = {
   serverExternalPackages: ['@node-rs/xxhash'],
 };
 
-// export default nextConfig;
-export default withWorkflow(nextConfig, { workflows: { lazyDiscovery: true } });
+export default withWorkflow(nextConfig);