workflow 5.0.1 → 5.1.0

package/docs/getting-started/fastify.mdx

@@ -72,12 +72,9 @@ export default defineNitroConfig({
 });
 ```
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      Setup IntelliSense for TypeScript (Optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary>Setup IntelliSense for TypeScript (Optional)</Summary>
+
 To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
@@ -93,9 +90,7 @@ To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.jso
 }
 ```
 
-    </AccordionContent>
-  </AccordionItem>
-</Accordion>
+</Details>
 
 ### Update `package.json`
 

package/docs/getting-started/hono.mdx

@@ -55,12 +55,9 @@ export default defineConfig({
 });
 ```
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      Setup IntelliSense for TypeScript (Optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary>Setup IntelliSense for TypeScript (Optional)</Summary>
+
 To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
@@ -76,10 +73,7 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 }
 ```
 
-    </AccordionContent>
-
-  </AccordionItem>
-</Accordion>
+</Details>
 
 ### Update `package.json`
 

package/docs/getting-started/index.mdx

@@ -80,14 +80,14 @@ import { SiReactrouter } from "@icons-pack/react-simple-icons";
       <div className="flex flex-col items-center justify-center gap-2">
         <Python className="size-16" />
         <span className="font-medium">Python</span>
-        <Badge variant="secondary">Beta</Badge>
+        <Badge variant="gray" size="sm">Beta</Badge>
       </div>
     </Card>
     <Card href="/docs/getting-started/nestjs">
       <div className="flex flex-col items-center justify-center gap-2">
         <Nest className="size-16 dark:invert" />
         <span className="font-medium">NestJS</span>
-        <Badge variant="secondary">Experimental</Badge>
+        <Badge variant="secondary">Beta</Badge>
       </div>
     </Card>
 </Cards>

package/docs/getting-started/nestjs.mdx

@@ -16,7 +16,7 @@ related:
 Set up your first durable workflow in a NestJS app and learn the core Workflow SDK concepts.
 
 <Callout>
-NestJS integration is experimental. Deployment to Vercel is supported via the
+NestJS integration is in beta. Deployment to Vercel is supported via the
 `workflow-nest build --vercel` command. See [Deploy to Vercel](#deploy-to-vercel) below.
 </Callout>
 
@@ -140,12 +140,9 @@ Add scripts to regenerate the SWC configuration before builds:
 }
 ```
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      Set up IntelliSense for TypeScript (optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary>Set up IntelliSense for TypeScript (optional)</Summary>
+
 To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
@@ -161,10 +158,7 @@ To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.jso
 }
 ```
 
-    </AccordionContent>
-
-  </AccordionItem>
-</Accordion>
+</Details>
 
 </Step>
 
@@ -384,10 +378,7 @@ import { AppModule } from '../dist/app.module.js';
 let ready: Promise<express.Express> | undefined;
 
 async function createHandler() {
-  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
-    bodyParser: false,
-  });
-  app.use(express.json());
+  const app = await NestFactory.create<NestExpressApplication>(AppModule);
   await app.init();
   return app.getHttpAdapter().getInstance();
 }
@@ -416,6 +407,16 @@ Deploy as usual. `workflow-nest build --vercel` runs automatically on Vercel (it
 `VERCEL` environment variable), writing `.vercel/output` with the consumer function so your runs
 execute instead of staying `pending`.
 
+<Callout type="info">
+The app is bundled with esbuild. A package that resolves a dependency at runtime
+behind a `try`/`catch` — a database driver reached through an ORM, an optional
+logger transport — looks like a hard dependency to the bundler, which fails the
+build on the first one your app has not installed. NestJS's own optional peers
+are handled for you; pass anything else to `--external`, for example
+`--external oracledb,mysql2`. Native addons (`*.node`) are not traced into the
+deployed function and are reported as a build warning.
+</Callout>
+
 </Step>
 
 </Steps>
@@ -473,6 +474,12 @@ WorkflowModule.forRoot({
   // (default: true, or false when VERCEL is set because dedicated functions
   // serve the bundles there).
   preloadBundles: true,
+
+  // Keep the application's body parser away from the workflow routes, so queue
+  // deliveries are not capped at Express's 100 KB limit and signed webhook
+  // bodies stay byte-exact (default: true). See "Request bodies and body
+  // parsers" below.
+  bypassBodyParser: true,
 });
 ```
 
@@ -521,41 +528,148 @@ function generates matching URLs:
 workflow-nest build --vercel --base-path /api
 ```
 
+<Callout type="info">
+`setGlobalPrefix(prefix, { exclude })` that excludes the workflow routes is
+honoured too: they stay at the origin root, and the SDK generates unprefixed
+URLs to match. `app.enableVersioning()` does not move them at all; see
+[Route versioning](#route-versioning).
+</Callout>
+
+---
+
+## Request bodies and body parsers
+
+The workflow routes are a byte pipe, in both directions and at whatever size the
+data happens to be:
+
+- The queue delivers run inputs, step inputs and step outputs in the body of a
+  `POST /.well-known/workflow/v1/flow`. Express caps request bodies at 100 KB
+  and NestJS installs that parser by default, so a workflow that passes an array
+  of any size around would get `413 request entity too large` on every delivery,
+  with nothing but a retry loop to show for it.
+- A webhook that verifies a signature over its raw body (Stripe, GitHub,
+  Shopify, Slack) only verifies if the bytes the sender signed arrive unchanged,
+  and a parser that has already turned the request into an object has destroyed
+  them.
+
+`WorkflowModule` handles both by keeping the application's body parsers away
+from `.well-known/workflow/v1`, and nothing else. On **Express**, workflow
+requests are read straight from the request stream, so they are neither
+size-limited nor re-serialized, and your own routes keep the parsers and limits
+you configured. No bootstrap configuration is needed, and `{ rawBody: true }` is
+not required for signed webhooks.
+
+Set `bypassBodyParser: false` to opt out and handle parsing yourself.
+
 <Callout type="warn">
-`app.enableVersioning()` moves the workflow routes the same way, and is not
-handled automatically. Exclude the workflow controller from versioning, or mount
-it where the SDK expects it.
+This stream bypass only applies to **uncompressed Express** requests. Two cases
+fall back to re-serializing the parsed body with `JSON.stringify`, which does
+**not** preserve whitespace or key order and therefore breaks webhook signature
+verification (Stripe, GitHub, Shopify, Slack):
+
+- **Fastify.** Fastify's content-type parser always consumes the request
+  stream before the route runs — `WorkflowModule` cannot stand it aside the way
+  it does Express's middleware — so the raw bytes are gone by the time the
+  handler sees them. Fastify's body limit is also enforced per instance rather
+  than per route; raise it on the adapter (for example
+  `new FastifyAdapter({ bodyLimit: 16 * 1024 * 1024 })`).
+- **Compressed bodies.** A body that arrives with a `content-encoding` always
+  goes through the parser on Express too, because that is what inflates it.
+
+For signed webhooks in either case, create the app with `{ rawBody: true }`
+(`NestFactory.create(AppModule, new FastifyAdapter(), { rawBody: true })` on
+Fastify) so the integration can recover the exact bytes the sender signed.
+NestJS keeps them on `req.rawBody` on both platforms, so no extra plugin is
+needed. Without it, the integration logs a one-time warning and falls back to
+the lossy `JSON.stringify` path.
 </Callout>
 
+<Callout type="info">
+On Vercel the flow and webhook routes are served by their own Build Output
+functions rather than by your NestJS app, so this only affects self-hosted
+deployments.
+</Callout>
+
+---
+
+## Guards, interceptors, and pipes
+
+The workflow routes are served by a controller inside your application, so a
+global guard runs for them too. A guard that rejects unauthenticated requests
+rejects every queue delivery and webhook with `403`, and runs stop making
+progress.
+
+Exempt them with `isWorkflowRequest`:
+
+{/*@skip-typecheck - Illustrates the pattern, not a complete app*/}
+
+```typescript
+import { Injectable, type CanActivate, type ExecutionContext } from '@nestjs/common';
+import { isWorkflowRequest } from 'workflow/nest';
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext) {
+    if (isWorkflowRequest(context)) return true;
+    // ...your own checks
+  }
+}
+```
+
+The workflow routes authenticate their own callers — queue deliveries are signed
+and webhook tokens are single-use secrets — so letting them past an application
+guard exposes nothing.
+
+Interceptors and exception filters are safe to leave in place. The handlers
+write through `@Res()`, so the exact status and body the workflow runtime
+produced reach the caller, which is what the queue and third-party webhook
+senders key off.
+
+---
+
+## Route versioning
+
+`app.enableVersioning()` moves every route under a version segment. The workflow
+controller is registered as `VERSION_NEUTRAL`, so it stays at
+`.well-known/workflow/v1` whichever strategy you enable, and the URLs the SDK
+generates keep resolving. A global prefix still applies on top, and is adopted
+automatically.
+
 ---
 
-## Raw request bodies
+## Fastify
 
-The workflow routes are a byte pipe. A webhook that verifies a signature over its
-raw body (Stripe, GitHub, Shopify, Slack) only works if the bytes the sender
-signed reach the workflow unchanged, and a body parser that has already turned
-the request into an object destroys them.
+`@nestjs/platform-fastify` is supported alongside `@nestjs/platform-express`,
+with two differences.
 
-Create the app with `rawBody` so the original bytes stay available:
+Fastify enforces its body limit before any content-type parser runs, and the
+limit is per instance rather than per route, so it cannot be scoped to the
+workflow routes. Raise it on the adapter; `WorkflowModule` warns at startup
+while it is still at Fastify's 1 MiB default:
 
 {/*@skip-typecheck - Bootstrap snippet*/}
 
 ```typescript
-const app = await NestFactory.create(AppModule, { rawBody: true });
+const app = await NestFactory.create(
+  AppModule,
+  new FastifyAdapter({ bodyLimit: 16 * 1024 * 1024 })
+);
 ```
 
-Without it, `@workflow/nest` falls back to re-serializing the parsed body with
-`JSON.stringify` and logs a warning once. That changes whitespace and key order,
-so signature verification fails.
+Fastify also answers content types it has no parser for with `415` before the
+request reaches a controller. Register a catch-all parser if your webhooks send
+`application/octet-stream` or another unparsed media type:
 
-Content types no body parser claims (XML, `application/x-www-form-urlencoded`
-without the parser registered, custom media types) are read straight from the
-request stream and need no configuration.
+{/*@skip-typecheck - Bootstrap snippet*/}
 
-<Callout type="info">
-On Vercel the webhook route is served by its own function rather than by your
-NestJS app, so this only affects self-hosted deployments.
-</Callout>
+```typescript
+app
+  .getHttpAdapter()
+  .getInstance()
+  .addContentTypeParser('*', { parseAs: 'buffer' }, (_request, body, done) =>
+    done(null, body)
+  );
+```
 
 ---
 
@@ -631,11 +745,18 @@ plain functions so the intent is clear.
   leave `skipBuild` unset so the bundles are built during startup. With
   `skipBuild` set and no bundles present, startup fails with an explicit error
   rather than serving broken workflow routes.
-- Create the app with `{ rawBody: true }` if you receive signed webhooks.
+- Exempt the workflow routes from any global guard with `isWorkflowRequest`, or
+  every queue delivery is rejected with `403`.
 - Set `basePath` (or rely on the adopted global prefix) so generated URLs match
   the routes NestJS serves.
 - Set `manageWorldLifecycle: true` for a self-hosted World, and call
   `app.enableShutdownHooks()` so the World is closed on a signal.
+- On Fastify, raise the adapter's `bodyLimit` above the data your workflows pass
+  between steps.
+- Install exactly one copy of `@nestjs/core`. With two, NestJS hands
+  `@workflow/nest` neither the global prefix nor the HTTP adapter, which
+  silently disables prefix handling and the body-parser bypass; a warning is
+  logged at startup when this happens.
 - `skipBuild` defaults to `true` when the `VERCEL` environment variable is set,
   so no Vercel-specific branch is needed in your module configuration.
 

package/docs/getting-started/next.mdx

@@ -52,12 +52,12 @@ const nextConfig: NextConfig = {
 export default withWorkflow(nextConfig); // [!code highlight]
 ```
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="text-sm">
-      ### Setup IntelliSense for TypeScript (Optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary className="[&_h3]:my-0">
+
+### Setup IntelliSense for TypeScript (Optional)
+
+</Summary>
 
 To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
 
@@ -74,16 +74,14 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 }
 ```
 
-    </AccordionContent>
-  </AccordionItem>
-</Accordion>
+</Details>
+
+<Details>
+<Summary className="[&_h3]:my-0">
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="configure-proxy-handler" className="[&_h3]:my-0">
-    <AccordionTrigger className="text-sm">
-      <h3 id="configure-proxy-handler">Configure Proxy Handler (if applicable)</h3>
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<h3 id="configure-proxy-handler" className="scroll-m-28">Configure Proxy Handler (if applicable)</h3>
+
+</Summary>
 
 If your Next.js app has a [proxy handler](https://nextjs.org/docs/app/api-reference/file-conventions/proxy)
 (formerly known as "middleware"), you'll need to update the matcher pattern to exclude Workflow's
@@ -113,9 +111,8 @@ export const config = {
 ```
 
 This ensures that internal Workflow paths are not intercepted by your middleware, which could interfere with workflow execution and resumption.
-    </AccordionContent>
-  </AccordionItem>
-</Accordion>
+
+</Details>
 
 </Step>
 

package/docs/getting-started/nitro.mdx

@@ -72,12 +72,9 @@ export default defineConfig({
 | `runtime` | `string` | `'nodejs22.x'` | Node.js runtime version for Vercel Functions (e.g. `'nodejs22.x'`, `'nodejs24.x'`). |
 | `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Defaults to `'inline'` in development and `false` in production (smaller function bundles, which helps stay under the Vercel 250 MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. |
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      Set up IntelliSense for TypeScript (optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary>Set up IntelliSense for TypeScript (optional)</Summary>
+
 To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
@@ -93,10 +90,7 @@ To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.jso
 }
 ```
 
-    </AccordionContent>
-
-  </AccordionItem>
-</Accordion>
+</Details>
 
 </Step>
 

package/docs/getting-started/nuxt.mdx

@@ -51,12 +51,9 @@ export default defineNuxtConfig({
 
 This will also automatically enable the TypeScript plugin, which provides helpful IntelliSense hints in your IDE for workflow and step functions.
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      Disable TypeScript Plugin (Optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary>Disable TypeScript Plugin (Optional)</Summary>
+
 The TypeScript plugin is enabled by default. If you need to disable it, you can configure it in your `nuxt.config.ts`:
 
 {/* @skip-typecheck: incomplete code sample */}
@@ -70,10 +67,7 @@ export default defineNuxtConfig({
 });
 ```
 
-    </AccordionContent>
-
-  </AccordionItem>
-</Accordion>
+</Details>
 
 </Step>
 

package/docs/getting-started/react-router/v7.mdx

@@ -18,41 +18,25 @@ This guide starts with an existing React Router v7 framework-mode app. It is ver
 
 ## Install Nitro and Workflow SDK
 
-<Tabs items={["npm", "pnpm", "bun", "yarn"]} defaultValue="pnpm">
+<CodeBlockTabs defaultValue="pnpm">
 
-<Tab value="npm">
-
-```bash
+```bash tab="npm"
 npm install nitro workflow
 ```
 
-</Tab>
-
-<Tab value="pnpm">
-
-```bash
+```bash tab="pnpm"
 pnpm add nitro workflow
 ```
 
-</Tab>
-
-<Tab value="bun">
-
-```bash
+```bash tab="bun"
 bun add nitro workflow
 ```
 
-</Tab>
-
-<Tab value="yarn">
-
-```bash
+```bash tab="yarn"
 yarn add nitro workflow
 ```
 
-</Tab>
-
-</Tabs>
+</CodeBlockTabs>
 
 This integration requires Nitro v3.
 

package/docs/getting-started/react-router/v8.mdx

@@ -18,41 +18,25 @@ This guide starts with an existing React Router v8 framework-mode app.
 
 ## Install Nitro and Workflow SDK
 
-<Tabs items={["npm", "pnpm", "bun", "yarn"]} defaultValue="pnpm">
+<CodeBlockTabs defaultValue="pnpm">
 
-<Tab value="npm">
-
-```bash
+```bash tab="npm"
 npm install nitro workflow
 ```
 
-</Tab>
-
-<Tab value="pnpm">
-
-```bash
+```bash tab="pnpm"
 pnpm add nitro workflow
 ```
 
-</Tab>
-
-<Tab value="bun">
-
-```bash
+```bash tab="bun"
 bun add nitro workflow
 ```
 
-</Tab>
-
-<Tab value="yarn">
-
-```bash
+```bash tab="yarn"
 yarn add nitro workflow
 ```
 
-</Tab>
-
-</Tabs>
+</CodeBlockTabs>
 
 This integration requires Nitro v3.
 

package/docs/getting-started/sveltekit.mdx

@@ -56,12 +56,12 @@ export default defineConfig({
 | --- | --- | --- | --- |
 | `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Defaults to `'inline'` in development and `false` in production (smaller function bundles, which helps stay under the Vercel 250 MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. |
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="text-sm">
-      ### Set up IntelliSense for TypeScript (optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary className="[&_h3]:my-0">
+
+### Set up IntelliSense for TypeScript (optional)
+
+</Summary>
 
 To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
@@ -78,9 +78,7 @@ To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.jso
 }
 ```
 
-    </AccordionContent>
-  </AccordionItem>
-</Accordion>
+</Details>
 
 </Step>
 

package/docs/getting-started/tanstack-start.mdx

@@ -57,12 +57,12 @@ export default defineConfig({
 });
 ```
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="text-sm">
-      ### Set up IntelliSense for TypeScript (optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary className="[&_h3]:my-0">
+
+### Set up IntelliSense for TypeScript (optional)
+
+</Summary>
 
 To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
@@ -79,9 +79,7 @@ To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.jso
 }
 ```
 
-    </AccordionContent>
-  </AccordionItem>
-</Accordion>
+</Details>
 
 </Step>
 

package/docs/getting-started/vite.mdx

@@ -61,12 +61,12 @@ export default defineConfig({
 });
 ```
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="text-sm">
-      ### Setup IntelliSense for TypeScript (Optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary className="[&_h3]:my-0">
+
+### Setup IntelliSense for TypeScript (Optional)
+
+</Summary>
 
 To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
 
@@ -83,9 +83,7 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 }
 ```
 
-    </AccordionContent>
-  </AccordionItem>
-</Accordion>
+</Details>
 
 </Step>