workflow 4.2.0-beta.76 → 4.2.0-beta.77

package/docs/deploying/world/vercel-world.mdx

@@ -139,12 +139,41 @@ On Vercel, workflow runs are pegged to the deployment that started them. This me
 
 This ensures long-running workflows complete reliably without being affected by subsequent deployments.
 
+## Security
+
+### Consumer function security
+
+Workflow handler functions on Vercel are not accessible through public endpoints. During the build step, the Workflow SDK registers each handler as only reachable by [Vercel Queue](https://vercel.com/docs/queues), by using the `experimentalTriggers` configuration in `.vc-config.json`:
+
+```json title=".vc-config.json (step handler)"
+{
+  "experimentalTriggers": [
+    {
+      "type": "queue/v2beta",
+      "topic": "__wkf_step_*",
+      "consumer": "default",
+    }
+  ]
+}
+```
+
+Practically, this means:
+
+- You don't need to add authentication or authorization logic to workflow handlers
+- Unauthorized requests can never reach the step or workflow functions
+- Only messages delivered through Vercel Queues can trigger execution
+- Handlers receive only a message ID that must be retrieved from Vercel's backend, making it impossible to craft custom payloads
+
+<Callout>
+  This configuration is managed entirely by the Workflow SDK build step. You should not need to write this yourself. If you are writing a custom integration, see [Framework Integrations — Security](/docs/how-it-works/framework-integrations#security) for more details.
+</Callout>
+
 ## How It Works
 
 The Vercel World uses Vercel's infrastructure for workflow execution:
 
 - **Storage** - Workflow data is stored in Vercel's cloud with automatic replication and [end-to-end encryption](/docs/how-it-works/encryption)
-- **Queuing** - Steps are distributed across serverless functions with automatic retries
+- **Queuing** - Steps are distributed across serverless functions via [Vercel Queues](https://vercel.com/docs/queues) with automatic retries and [consumer function security](#consumer-function-security)
 - **Authentication** - OIDC tokens provide secure, automatic authentication
 
 For more details, see the [Vercel Workflow documentation](https://vercel.com/docs/workflow).

package/docs/errors/hook-conflict.mdx

@@ -15,7 +15,7 @@ This error occurs when you try to create a hook with a token that is already in
 ## Error Message
 
 ```
-Hook token conflict: Hook with token <token> already exists for this project
+Hook token "<token>" is already in use by another workflow
 ```
 
 ## Why This Happens

package/docs/errors/node-js-module-in-workflow.mdx

@@ -69,7 +69,7 @@ async function read(filePath: string) {
 These common Node.js core modules cannot be used in workflow functions:
 
 - File system: `fs`, `path`
-- Network: `http`, `https`, `net`, `dns`, `fetch`
+- Network: `http`, `https`, `net`, `dns`
 - Process: `child_process`, `cluster`
 - Crypto: `crypto` (use Web Crypto API instead)
 - Operating system: `os`

package/docs/errors/start-invalid-workflow-function.mdx

@@ -1,107 +1,132 @@
 ---
 title: start-invalid-workflow-function
-description: Ensure you pass a valid workflow function to start() with proper configuration.
+description: The function passed to start() must be a transformed workflow function.
 type: troubleshooting
-summary: Resolve the start-invalid-workflow-function error by passing a properly configured workflow function.
+summary: Fix invalid workflow function errors by adding "use workflow" and enabling your framework integration.
 prerequisites:
   - /docs/foundations/starting-workflows
 related:
   - /docs/api-reference/workflow-api/start
+  - /docs/getting-started/next
+  - /docs/api-reference/workflow-next/with-workflow
 ---
 
-This error occurs when you try to call `start()` with a function that is not a valid workflow function or when the Workflow SDK is not configured correctly.
+This error occurs when `start()` receives a function that does not have Workflow SDK's generated workflow metadata. In practice, that usually means the function is missing `"use workflow"` or the file was never transformed by your framework integration.
 
 ## Error Message
 
 ```
-'start' received an invalid workflow function. Ensure the Workflow SDK
-is configured correctly and the function includes a 'use workflow' directive.
+'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.
 ```
 
 ## Why This Happens
 
-The `start()` function expects a workflow function that has been properly processed by Workflow SDK's build system. During the build process, workflow functions are transformed and marked with special metadata that `start()` uses to identify and execute them.
-
-This error typically happens when:
-
-* The function is missing the `"use workflow"` directive
-* The workflow isn't being built/transformed correctly
-* The function isn't exported from the workflow file
-* The wrong function is being imported
+`start()` expects an imported workflow function, not just any async function. During compilation, Workflow SDK transforms files that contain `"use workflow"` and attaches generated metadata such as the workflow ID. If that transform never runs, or if you pass a wrapper function instead of the transformed export, `start()` cannot identify what to enqueue and throws this error.
 
 ## Common Causes
 
-### Missing `"use workflow"` Directive
+### Missing `"use workflow"`
 
-```typescript lineNumbers title="workflows/order.ts"
-// Error - missing directive
-export async function processOrder(orderId: string) { // [!code highlight]
-  // workflow logic
-  return { status: "completed" };
-}
-```
+{/* @skip-typecheck: incomplete code sample */}
+```typescript lineNumbers
+import { start } from "workflow/api";
 
-**Solution:** Add the `"use workflow"` directive.
+export async function sendReminder(email: string) {
+  await sendEmail(email);
+}
 
-```typescript lineNumbers title="workflows/order.ts"
-// Fixed - includes directive
-export async function processOrder(orderId: string) {
-  "use workflow"; // [!code highlight]
+export async function POST() {
+  await start(sendReminder, ["hello@example.com"]);
+  return new Response("ok");
+}
 
-  // workflow logic
-  return { status: "completed" };
+async function sendEmail(email: string) {
+  "use step";
+  console.log(`Sending email to ${email}`);
 }
 ```
 
-### Incorrect Import
+**Fix:** Add `"use workflow"` to the workflow function.
 
-```typescript lineNumbers title="app/api/route.ts"
+{/* @skip-typecheck: incomplete code sample */}
+```typescript lineNumbers
 import { start } from "workflow/api";
-// Error - importing step function instead of workflow
-import { processStep } from "@/workflows/order"; // [!code highlight]
 
-export async function POST(request: Request) {
-  await start(processStep, ["order-123"]); // Error! // [!code highlight]
-  return Response.json({ started: true });
+export async function sendReminder(email: string) {
+  "use workflow"; // [!code highlight]
+  await sendEmail(email);
 }
-```
 
-**Solution:** Import the correct workflow function.
-
-```typescript lineNumbers title="app/api/route.ts"
-import { start } from "workflow/api";
-// Fixed - import workflow function
-import { processOrder } from "@/workflows/order"; // [!code highlight]
+export async function POST() {
+  await start(sendReminder, ["hello@example.com"]); // [!code highlight]
+  return new Response("ok");
+}
 
-export async function POST(request: Request) {
-  await start(processOrder, ["order-123"]); // [!code highlight]
-  return Response.json({ started: true });
+async function sendEmail(email: string) {
+  "use step";
+  console.log(`Sending email to ${email}`);
 }
 ```
 
-### Next.js Configuration Missing
+### Missing `withWorkflow()` in `next.config.ts`
 
-```typescript lineNumbers title="next.config.ts"
-// Error - missing withWorkflow wrapper
+{/* @skip-typecheck: incomplete code sample */}
+```typescript title="next.config.ts" lineNumbers
 import type { NextConfig } from "next";
 
-const nextConfig: NextConfig = {
-  // your config
-};
+const nextConfig: NextConfig = {};
 
 export default nextConfig;
 ```
 
-**Solution:** Wrap with `withWorkflow()`.
+**Fix:** Wrap the config with `withWorkflow()` so workflow files are transformed.
 
-```typescript lineNumbers title="next.config.ts"
-// Fixed - includes withWorkflow
-import { withWorkflow } from "workflow/next"; // [!code highlight}
+```typescript title="next.config.ts" lineNumbers
 import type { NextConfig } from "next";
+import { withWorkflow } from "workflow/next"; // [!code highlight]
 
-const nextConfig: NextConfig = {
-  // your config
-};
+const nextConfig: NextConfig = {};
 
 export default withWorkflow(nextConfig); // [!code highlight]
 ```
+
+### Passing a wrapper function instead of the imported workflow
+
+{/* @skip-typecheck: incomplete code sample */}
+```typescript lineNumbers
+import { start } from "workflow/api";
+import { sendReminder } from "./workflows/send-reminder";
+
+export async function POST() {
+  // Does NOT work
+  await start(async () => sendReminder("hello@example.com"));
+  return new Response("ok");
+}
+```
+
+**Fix:** Pass the imported workflow function directly and provide arguments in the second parameter.
+
+```typescript lineNumbers
+import { start } from "workflow/api";
+import { sendReminder } from "./workflows/send-reminder";
+
+export async function POST() {
+  await start(sendReminder, ["hello@example.com"]); // [!code highlight]
+  return new Response("ok");
+}
+```
+
+## Checklist
+
+Before calling `start()`:
+
+1. Confirm the function includes `"use workflow"` as its first statement.
+2. Confirm your framework integration is enabled (for Next.js, wrap `next.config.ts` with [`withWorkflow()`](/docs/api-reference/workflow-next/with-workflow)).
+3. Pass the imported workflow function directly to `start()`, not a wrapper callback.
+4. Keep the function in a file that goes through Workflow DevKit's transform step.
+
+## Related
+
+- [`start()`](/docs/api-reference/workflow-api/start)
+- [`withWorkflow()`](/docs/api-reference/workflow-next/with-workflow)
+- [Next.js Getting Started](/docs/getting-started/next)

package/docs/foundations/starting-workflows.mdx

@@ -144,7 +144,7 @@ export async function POST(request: Request) {
 }
 ```
 
-Your workflow can write to the stream using [`getWritable()`](/docs/api-reference/workflow/get-writable):
+Your workflow can obtain a writable stream using [`getWritable()`](/docs/api-reference/workflow/get-writable):
 
 ```typescript lineNumbers
 import { getWritable } from "workflow";

package/docs/foundations/streaming.mdx

@@ -44,7 +44,7 @@ Use the `Run` object's `readable` property to consume the stream from your API r
 
 ```typescript title="app/api/stream/route.ts" lineNumbers
 import { start } from "workflow/api";
-import { simpleStreamingWorkflow } from "./workflows/simple";
+import { simpleStreamingWorkflow } from "./workflows/simple-streaming";
 
 export async function POST() {
   const run = await start(simpleStreamingWorkflow);

package/docs/getting-started/astro.mdx

@@ -235,6 +235,23 @@ npx astro add vercel
 
 Additionally, check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+If you see this error:
+
+```
+'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your `astro.config.mjs` includes the `workflow()` integration.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 * Learn more about the [Foundations](/docs/foundations).

package/docs/getting-started/express.mdx

@@ -262,6 +262,23 @@ Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.c
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+If you see this error:
+
+```
+'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your Nitro config includes the `workflow/nitro` module.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

package/docs/getting-started/fastify.mdx

@@ -249,6 +249,23 @@ Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.c
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+If you see this error:
+
+```
+'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your Nitro config includes the `workflow/nitro` module.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

package/docs/getting-started/hono.mdx

@@ -244,6 +244,23 @@ Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.c
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+If you see this error:
+
+```
+'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your Nitro config includes the `workflow/nitro` module.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

package/docs/getting-started/nestjs.mdx

@@ -41,15 +41,18 @@ cd my-workflow-app
 npm i workflow @workflow/nest
 ```
 
-### Configure NestJS for ESM
+### Choose Your Module Format
 
-NestJS with SWC uses ES modules. Add `"type": "module"` to your `package.json`:
+NestJS projects using `@workflow/nest` can compile as either ESM or CommonJS. Choose the setup that matches your SWC output instead of assuming ESM is required.
+
+#### ESM (default)
+
+Use this when your NestJS project is configured as an ES module app.
 
 ```json title="package.json" lineNumbers
 {
   "name": "my-workflow-app",
-  "type": "module",
-  // ... rest of your config
+  "type": "module"
 }
 ```
 
@@ -57,6 +60,29 @@ NestJS with SWC uses ES modules. Add `"type": "module"` to your `package.json`:
 When using ESM with NestJS, local imports must include the `.js` extension (e.g., `import { AppModule } from './app.module.js'`). This applies even though your source files are `.ts`.
 </Callout>
 
+#### CommonJS
+
+Use this when your NestJS project compiles CommonJS via SWC.
+
+```typescript title="src/app.module.ts" lineNumbers
+import { Module } from '@nestjs/common';
+import { WorkflowModule } from '@workflow/nest';
+
+@Module({
+  imports: [
+    WorkflowModule.forRoot({
+      moduleType: 'commonjs',
+      distDir: 'dist',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+<Callout type="info">
+`distDir` should match the directory where NestJS writes compiled `.js` files. In the default SWC setup, that is `dist`.
+</Callout>
+
 ### Configure NestJS to use SWC
 
 NestJS supports SWC as an alternative compiler for faster builds. The Workflow SDK uses an SWC plugin to transform workflow files.
@@ -141,7 +167,7 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 
 ## Import the WorkflowModule
 
-In your `app.module.ts`, import the `WorkflowModule`:
+In your `app.module.ts`, import the `WorkflowModule` and keep the module format you chose above.
 
 ```typescript title="src/app.module.ts" lineNumbers
 import { Module } from '@nestjs/common';
@@ -157,6 +183,20 @@ import { AppService } from './app.service.js';
 export class AppModule {}
 ```
 
+<Callout type="info">
+If you chose CommonJS above, keep the CommonJS options here as well:
+
+{/* @skip-typecheck - config snippet, full import shown above */}
+```typescript
+WorkflowModule.forRoot({
+  moduleType: 'commonjs',
+  distDir: 'dist',
+})
+```
+
+The `.js` local import specifiers in this example are the ESM form.
+</Callout>
+
 The `WorkflowModule` handles workflow bundle building and provides HTTP routing for workflow execution at `.well-known/workflow/v1/`.
 
 </Step>
@@ -171,6 +211,15 @@ Create a new file for our first workflow in the `src/workflows` directory:
 Workflow files must be inside the `src/` directory so they get compiled with the SWC plugin that enables the `start()` function to work correctly.
 </Callout>
 
+<Callout type="info">
+If `start()` says it received an invalid workflow function, check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. The workflow file lives inside `src/` so NestJS compiles it with the SWC plugin.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+</Callout>
+
 ```typescript title="src/workflows/user-signup.ts" lineNumbers
 import { sleep } from "workflow";
 
@@ -269,6 +318,10 @@ export class AppController {
 }
 ```
 
+<Callout type="info">
+If you chose CommonJS above, use the same local import style as the rest of your NestJS app here too. The `.js` extension shown in this example is the ESM form.
+</Callout>
+
 This creates a `POST` endpoint at `/signup` that will trigger your workflow.
 
 </Step>
@@ -324,9 +377,34 @@ WorkflowModule.forRoot({
 
   // Skip building in production when bundles are pre-built
   skipBuild: false,
+
+  // SWC module type: 'es6' (default) or 'commonjs'
+  // Set to 'commonjs' if your NestJS project compiles to CJS via SWC
+  moduleType: 'es6',
+
+  // Directory where NestJS compiles .ts to .js (default: 'dist')
+  // Only used when moduleType is 'commonjs'
+  // Should match the outDir in your tsconfig.json
+  distDir: 'dist',
 });
 ```
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+If you see this error:
+
+```
+'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your NestJS app imports and registers the `WorkflowModule`.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

package/docs/getting-started/next.mdx

@@ -275,12 +275,27 @@ Build error occurred
 Error: Cannot find module 'next/dist/lib/server-external-packages.json'
 ```
 
-Upgrade to `workflow@4.0.1-beta.26` or later:
+Upgrade to `workflow@4.2.0` or later:
 
 ```package-install
 workflow@latest
 ```
 
+### `start()` says it received an invalid workflow function
+
+If you see this error:
+
+```
+'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your `next.config.ts` is wrapped with [`withWorkflow()`](/docs/api-reference/workflow-next/with-workflow).
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 * Learn more about the [Foundations](/docs/foundations).

package/docs/getting-started/nitro.mdx

@@ -228,6 +228,23 @@ Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.c
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+If you see this error:
+
+```
+'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your Nitro config includes the `workflow/nitro` module.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

package/docs/getting-started/nuxt.mdx

@@ -229,6 +229,23 @@ Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.c
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+If you see this error:
+
+```
+'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your `nuxt.config.ts` includes the `workflow/nuxt` module.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

package/docs/getting-started/sveltekit.mdx

@@ -228,6 +228,23 @@ Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.c
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+If you see this error:
+
+```
+'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your `vite.config.ts` includes the `workflow/sveltekit` plugin.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 * Learn more about the [Foundations](/docs/foundations).

package/docs/getting-started/vite.mdx

@@ -234,6 +234,23 @@ Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.c
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+If you see this error:
+
+```
+'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your `vite.config.ts` includes the `workflow/vite` plugin.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 * Learn more about the [Foundations](/docs/foundations).