workflow 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/api-reference/{workflow-api → workflow-runtime}/world/storage.mdx

@@ -4,11 +4,11 @@ description: Query workflow runs, steps, hooks, and the underlying event log via
 type: reference
 summary: "Interfaces: world.events, world.runs, world.steps, world.hooks. Events are the source of truth; runs, steps, and hooks are materialized views."
 prerequisites:
-  - /docs/api-reference/workflow-api/get-world
+  - /docs/api-reference/workflow-runtime/get-world
 related:
   - /docs/api-reference/workflow-api/get-run
   - /docs/how-it-works/event-sourcing
-  - /docs/api-reference/workflow-api/world/observability
+  - /docs/api-reference/workflow-observability
 keywords:
   - world.events
   - world.runs
@@ -31,8 +31,8 @@ keywords:
 
 The World storage interface exposes four sub-interfaces for querying workflow data:
 
-- **`world.events`** — The append-only event log. This is the source of truth for all workflow state. See [Event Sourcing](/docs/how-it-works/event-sourcing) for background.
-- **`world.runs`**, **`world.steps`**, **`world.hooks`** — Materialized views derived from the event log, provided as convenience accessors for the most common query patterns.
+- **`world.events`**: The append-only event log. This is the source of truth for all workflow state. See [Event Sourcing](/docs/how-it-works/event-sourcing) for background.
+- **`world.runs`**, **`world.steps`**, **`world.hooks`**: Materialized views derived from the event log, provided as convenience accessors for the most common query patterns.
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -62,7 +62,7 @@ await world.events.create(runId, { // [!code highlight]
 | `data` | `CreateEventRequest` | Event data including `eventType` |
 | `params` | `object` | Optional parameters |
 
-**Returns:** `EventResult` — The created event and the affected entity (run/step/hook)
+**Returns:** `EventResult`, the created event and the affected entity (run/step/hook)
 
 ### events.get()
 
@@ -81,7 +81,8 @@ const event = await world.events.get(runId, eventId); // [!code highlight]
 
 ### events.list()
 
-List events for a run with cursor pagination.
+List events for a run. Omit `pagination.limit` to return every remaining event,
+or set it to return one bounded page.
 
 ```typescript lineNumbers
 const result = await world.events.list({ runId, pagination: { cursor } }); // [!code highlight]
@@ -91,31 +92,39 @@ const result = await world.events.list({ runId, pagination: { cursor } }); // [!
 |-----------|------|-------------|
 | `params.runId` | `string` | Filter events by run ID |
 | `params.pagination.cursor` | `string` | Cursor for the next page |
+| `params.pagination.limit` | `number` | Maximum events to return. When omitted, returns every remaining event up to the World's event ceiling. |
+| `params.pagination.sortOrder` | `"asc" \| "desc"` | Event order |
+| `params.resolveData` | `"all" \| "none"` | Include or omit event payload data |
 
-**Returns:** `{ data: Event[], cursor?: string }`
+**Returns:** `{ data: Event[], cursor: string | null, hasMore: boolean }`
 
 ### events.listByCorrelationId()
 
-List events that share a correlation ID, useful for tracing related events across runs.
+List one run's events that share a correlation ID, useful for tracing a single step, hook or wait through its lifecycle.
+
+A correlation ID is unique within its run, not across runs: two runs can each hold a `step_…`, `hook_…` or `wait_…` ID that reads the same. `runId` is therefore required, and it is also what makes the pagination cursor unambiguous.
 
 ```typescript lineNumbers
 const result = await world.events.listByCorrelationId({ // [!code highlight]
+  runId,
   correlationId: "order-123",
 }); // [!code highlight]
 ```
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
+| `params.runId` | `string` | The run the correlation ID belongs to |
 | `params.correlationId` | `string` | The correlation ID to filter by |
 | `params.pagination.cursor` | `string` | Cursor for the next page |
 
 **Returns:** `{ data: Event[], cursor?: string }`
 
-### Event Types
+### Event types
 
 | Category | Types |
 |----------|-------|
 | Run | `run_created`, `run_started`, `run_completed`, `run_failed`, `run_cancelled` |
+| Attribute | `attr_set` |
 | Step | `step_created`, `step_started`, `step_completed`, `step_failed`, `step_retrying` |
 | Hook | `hook_created`, `hook_received`, `hook_disposed`, `hook_conflict` |
 | Wait | `wait_created`, `wait_completed` |
@@ -124,7 +133,10 @@ const result = await world.events.listByCorrelationId({ // [!code highlight]
 
 ## world.runs
 
-Materialized from run events. Use it to list and inspect workflow runs.
+Materialized from run events. Use it for canonical operational reads, including
+reads that require workflow input or output data. For observability dashboards,
+inspection tools, and historical listings, use
+[`world.analytics.runs.list()`](/docs/api-reference/workflow-runtime/world/analytics#runslist).
 
 ### runs.get()
 
@@ -139,6 +151,40 @@ const run = await world.runs.get(runId); // [!code highlight]
 
 **Returns:** `WorkflowRun` (or `WorkflowRunWithoutData` when `resolveData: 'none'`)
 
+### runs.waitForTerminalStatus()
+
+Optional. Long poll for a run to reach a terminal status (`completed`,
+`failed`, or `cancelled`) instead of re-reading it on an interval. This is what
+`await run.returnValue` uses, so a run's result reaches the awaiting side as
+soon as it finishes rather than at the next poll tick.
+
+```typescript lineNumbers
+const run = await world.runs.waitForTerminalStatus?.(runId, { // [!code highlight]
+  timeoutMs: 25_000, // [!code highlight]
+}); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `params.timeoutMs` | `number` | Upper bound on the wait. The call returns earlier, the moment the run is terminal |
+| `params.signal` | `AbortSignal` | Abandons the wait |
+| `params.resolveData` | `'all' \| 'none'` | Whether to include input/output data. Default: `'all'` |
+
+**Returns:** the same `WorkflowRun` as `runs.get()`: terminal if the run
+finished within the budget, otherwise the latest snapshot. An expired budget is
+a normal return, not an error, and a missing run throws
+`WorkflowRunNotFoundError` exactly as `runs.get()` does.
+
+<Callout>
+  Not every backend can hold a read open, so this method is optional and may
+  also return a non-terminal snapshot before `timeoutMs` is up. Callers pace
+  their own retries (`await run.returnValue` keeps consecutive non-terminal
+  observations at least one `WORKFLOW_RETURN_VALUE_POLL_INTERVAL_MS` apart), and
+  worlds that omit the method are polled on that interval instead. Set
+  `WORKFLOW_RETURN_VALUE_LONG_POLL=0` to force interval polling everywhere.
+</Callout>
+
 ### runs.list()
 
 ```typescript lineNumbers
@@ -154,11 +200,21 @@ const result = await world.runs.list({ // [!code highlight]
 
 **Returns:** `{ data: WorkflowRun[], cursor?: string }`
 
-### Cancelling Runs
+<Callout type="warn">
+  Observability and inspection usage of `world.runs.list()` is deprecated. Use
+  [`world.analytics.runs.list()`](/docs/api-reference/workflow-runtime/world/analytics#runslist)
+  for metadata-only, plan-aware queries backed by the observability pipeline.
+  `world.runs.list()` remains supported for operational and payload-bearing
+  reads.
+</Callout>
+
+### Cancelling runs
 
-To cancel a run, create a `run_cancelled` event via `world.events.create()` (see [world.events](#worldevents) above), or use the CLI or Web UI helpers.
+To cancel a run, create a `run_cancelled` event through `world.events.create()` (see [world.events](#worldevents) above), or use the Workflow CLI or web interface helpers.
 
-### WorkflowRun Type
+To cancel a batch in one call, a world may implement the optional `runs.cancelMany({ runIds })`. It returns a summary plus a per-run outcome (`cancelled`, `already_cancelled`, `not_cancellable`, `not_found`, or `failed`). Backends that omit it fall back to per-run cancellation automatically.
+
+### WorkflowRun type
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -189,7 +245,7 @@ const step = await world.steps.get(runId, stepId); // [!code highlight]
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `runId` | `string \| undefined` | The workflow run ID |
+| `runId` | `string` | The workflow run ID that owns the step |
 | `stepId` | `string` | The step ID |
 | `params.resolveData` | `'all' \| 'none'` | Whether to include input/output data. Default: `'all'` |
 
@@ -212,7 +268,7 @@ const result = await world.steps.list({ // [!code highlight]
 
 **Returns:** `{ data: Step[], cursor?: string }`
 
-### Step Type
+### Step type
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -229,11 +285,11 @@ const result = await world.steps.list({ // [!code highlight]
 | `retryAfter` | `string \| null` | ISO timestamp for next retry attempt |
 
 <Callout type="info">
-  Step I/O is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Use `hydrateResourceIO()` from `workflow/observability` to deserialize it for display. See [Observability Utilities](/docs/api-reference/workflow-api/world/observability).
+  Step input/output (I/O) is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Use `hydrateResourceIO()` from `workflow/observability` to deserialize it for display. See [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io).
 </Callout>
 
 <Callout type="warn">
-  `stepName` is a machine-readable identifier like `step//./src/workflows/order//processPayment`. Use `parseStepName()` from `workflow/observability` to extract the `shortName` for UI display.
+  `stepName` is a machine-readable identifier like `step//./src/workflows/order//processPayment`. Use `parseStepName()` from `workflow/observability` to extract the `shortName` for display in a user interface.
 </Callout>
 
 ---
@@ -258,6 +314,12 @@ const hook = await world.hooks.get(hookId); // [!code highlight]
 
 Look up a hook by its token. Useful in webhook resume flows where you receive a token in the callback URL.
 
+<Callout type="info">
+For runtime application code, prefer [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token). Use `world.hooks.getByToken()` when you are working directly with the World storage interface for custom tooling, admin views, or low-level integrations.
+
+Hook-token lookup is the low-level form of the recommended idempotency flow: if a hook is already registered for your business key, reuse the hook's `runId` or resume that hook instead of starting another run. If no hook exists yet, start a workflow that creates the deterministic hook near the beginning and checks `await hook.getConflict()` to detect whether another run claimed the token first. On a conflict it resolves with the run that owns the token. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript lineNumbers
 const hook = await world.hooks.getByToken(token); // [!code highlight]
 ```
@@ -282,7 +344,7 @@ const result = await world.hooks.list({ // [!code highlight]
 
 **Returns:** `{ data: Hook[], cursor?: string }`
 
-### Hook Type
+### Hook type
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -299,7 +361,7 @@ const result = await world.hooks.list({ // [!code highlight]
 
 ## Examples
 
-### List Runs with Pagination
+### List runs with pagination
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -314,23 +376,23 @@ const runs = await world.runs.list({ // [!code highlight]
 cursor = runs.cursor; // pass to next call for pagination
 ```
 
-### Get a Run — Full Data vs. Metadata Only
+### Get a run: full data vs. metadata only
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
 const world = await getWorld();
 
-// Full data (default) — includes serialized input/output
+// Full data (default): includes serialized input/output
 const run = await world.runs.get(runId); // [!code highlight]
 
-// Metadata only — lighter, no I/O loaded
+// Metadata only: lighter, no I/O loaded
 const lightweight = await world.runs.get(runId, { // [!code highlight]
   resolveData: "none", // [!code highlight]
 }); // [!code highlight]
 ```
 
-### List Steps for a Progress Dashboard
+### List steps for a progress dashboard
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -352,7 +414,7 @@ const progress = steps.data.map((step) => {
 });
 ```
 
-### Hydrate Step I/O
+### Hydrate step I/O
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -364,7 +426,7 @@ const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highl
 console.log(hydrated.input, hydrated.output);
 ```
 
-### Cancel a Run
+### Cancel a run
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -375,17 +437,19 @@ await world.events.create(runId, { // [!code highlight]
 }); // [!code highlight]
 ```
 
-### Look Up Hook by Token
+### Look up hook by token
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
 const world = await getWorld();
 const hook = await world.hooks.getByToken(token); // [!code highlight]
-console.log(hook.runId, hook.metadata); // [!code highlight]
+console.log(hook.runId); // [!code highlight]
 ```
 
-### List Events for Audit Trail
+The World-level `Hook` carries `metadata` as the raw serialized (and, on encrypting Worlds, encrypted) value, not the object the workflow passed to `createHook()`. To read the decoded value, use [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token), whose `hook.metadata` is a Promise that hydrates it on first access.
+
+### List events for audit trail
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -400,9 +464,9 @@ for (const event of events.data) {
 
 ## Related
 
-- [Event Sourcing](/docs/how-it-works/event-sourcing) — How the event log powers workflow replay and state
-- [getRun()](/docs/api-reference/workflow-api/get-run) — Higher-level API for working with individual runs
-- [Observability Utilities](/docs/api-reference/workflow-api/world/observability) — Hydrate step I/O, parse display names, decrypt data
-- [resumeHook()](/docs/api-reference/workflow-api/resume-hook) — Resume a workflow by sending a payload to a hook
-- [Hooks](/docs/foundations/hooks) — Core concepts for hooks and pause points
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) — Core concepts for steps
+- [Event sourcing](/docs/how-it-works/event-sourcing): How the event log powers workflow replay and state
+- [`getRun()`](/docs/api-reference/workflow-api/get-run): Higher-level API for working with individual runs
+- [`workflow/observability`](/docs/api-reference/workflow-observability): Hydrate step I/O and parse display names
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook): Resume a workflow by sending a payload to a hook
+- [Hooks](/docs/foundations/hooks): Core concepts for hooks and pause points
+- [Workflows and steps](/docs/foundations/workflows-and-steps): Core concepts for steps

package/docs/api-reference/{workflow-api → workflow-runtime}/world/streams.mdx

@@ -4,7 +4,7 @@ description: Read, write, and manage real-time data streams for workflow runs.
 type: reference
 summary: "Methods: streams.write(), streams.writeMulti(), streams.get(), streams.close(), streams.list(), streams.getChunks(), streams.getInfo(). Stream methods live on world.streams."
 prerequisites:
-  - /docs/api-reference/workflow-api/get-world
+  - /docs/api-reference/workflow-runtime/get-world
 related:
   - /docs/foundations/streaming
   - /docs/api-reference/workflow/get-writable
@@ -33,7 +33,7 @@ Stream methods live on `world.streams` (the `streams` sub-object of the `World`
 import { getWorld } from "workflow/runtime";
 
 const world = await getWorld(); // [!code highlight]
-// Stream methods are called on world.streams — e.g. world.streams.write()
+// Stream methods are called on world.streams, e.g. world.streams.write()
 ```
 
 ## Methods
@@ -56,7 +56,7 @@ await world.streams.write(runId, "default", chunk); // [!code highlight]
 
 ### writeMulti()
 
-Write multiple chunks in a single operation. Optional optimization — not all World implementations support it. Falls back to sequential `write()` calls if unavailable.
+Write multiple chunks in a single operation. Optional optimization: not all World implementations support it. Falls back to sequential `write()` calls if unavailable.
 
 ```typescript lineNumbers
 await world.streams.writeMulti?.(runId, "default", [chunk1, chunk2]); // [!code highlight]
@@ -173,7 +173,7 @@ const info = await world.streams.getInfo(runId, "default"); // [!code highlight]
 
 ## Examples
 
-### Read a Stream as a Response
+### Read a stream as a response
 
 ```typescript lineNumbers
 // app/api/workflow-streams/read/route.ts
@@ -192,7 +192,7 @@ export async function GET(req: Request) {
 }
 ```
 
-### Paginate Through Stream Chunks
+### Paginate through stream chunks
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -211,6 +211,6 @@ do {
 
 ## Related
 
-- [Streaming](/docs/foundations/streaming) — Core concepts for streaming data from workflows
-- [getWritable()](/docs/api-reference/workflow/get-writable) — The standard way to write to streams from within steps
-- [Storage](/docs/api-reference/workflow-api/world/storage) — Query runs, steps, hooks, and events
+- [Streaming](/docs/foundations/streaming): Core concepts for streaming data from workflows
+- [`getWritable()`](/docs/api-reference/workflow/get-writable): The standard way to write to streams from within steps
+- [Storage](/docs/api-reference/workflow-runtime/world/storage): Query runs, steps, hooks, and events

package/docs/api-reference/workflow-serde/index.mdx

@@ -27,9 +27,8 @@ The `@workflow/serde` package provides two symbols that allow you to define cust
     </Card>
 </Cards>
 
-## Quick Example
+## Quick example
 
-{/* @expect-error:2351 */}
 
 ```typescript lineNumbers
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";

package/docs/api-reference/workflow-serde/workflow-deserialize.mdx

@@ -6,7 +6,6 @@ A symbol used to define custom deserialization for user-defined class instances.
 
 ## Usage
 
-{/* @expect-error:2351 */}
 
 ```typescript lineNumbers
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
@@ -24,9 +23,9 @@ class Point {
 }
 ```
 
-## API Signature
+## API signature
 
-{/* @skip-typecheck */}
+{/* @skip-typecheck: type-only signature snippet, not compilable code */}
 
 ```typescript
 static [WORKFLOW_DESERIALIZE](data: SerializableData): T
@@ -66,5 +65,5 @@ This method runs inside the workflow context and is subject to the same constrai
 - No non-deterministic operations (like `Math.random()` or `Date.now()`)
 - No external network calls
 
-Keep this method simple and focused on reconstructing the instance from the provided data.
+Keep this method focused on reconstructing the instance from the provided data.
 </Callout>

package/docs/api-reference/workflow-serde/workflow-serialize.mdx

@@ -2,11 +2,10 @@
 title: WORKFLOW_SERIALIZE
 ---
 
-A symbol used to define custom serialization for user-defined class instances. The static method should accept an instance and return serializable data.
+`WORKFLOW_SERIALIZE` defines custom serialization for user-defined class instances. The static method accepts an instance and returns serializable data.
 
 ## Usage
 
-{/* @expect-error:2351 */}
 
 ```typescript lineNumbers
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
@@ -24,9 +23,9 @@ class Point {
 }
 ```
 
-## API Signature
+## API signature
 
-{/* @skip-typecheck */}
+{/* @skip-typecheck: type-only signature snippet, not compilable code */}
 
 ```typescript
 static [WORKFLOW_SERIALIZE](instance: T): SerializableData
@@ -61,15 +60,16 @@ The method should return serializable data. This can be:
 The method must be implemented as a **static** method on the class. Instance methods are not supported.
 </Callout>
 
-- Both `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` must be implemented together
-- The returned data must itself be serializable
-- The SWC compiler plugin automatically detects and registers classes that implement these symbols
+- Both `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` must be implemented together.
+- The returned data must itself be serializable.
+- The SWC compiler plugin automatically detects and registers classes that implement these symbols.
 
 <Callout type="warn">
 This method runs inside the workflow context and is subject to the same constraints as `"use workflow"` functions:
 - No Node.js-specific APIs (like `fs`, `path`, `crypto`, etc.)
 - No non-deterministic operations (like `Math.random()` or `Date.now()`)
 - No external network calls
+- No side effects on workflow state: the method may run outside deterministic replay, so mutations would not be reconstructed
 
-Keep this method simple and focused on extracting data from the instance.
+Keep this method focused on extracting data from the instance.
 </Callout>

package/docs/api-reference/workflow-sveltekit/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "workflow/sveltekit"
+description: SvelteKit integration for automatic workflow bundling via Vite.
+type: overview
+summary: Explore the SvelteKit integration for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/sveltekit
+---
+
+SvelteKit integration for Workflow SDK that configures Vite to transform workflow code and build the workflow bundles.
+
+## Functions
+
+<Cards>
+    <Card title="workflowPlugin()" href="/docs/api-reference/workflow-sveltekit/workflow-plugin">
+        Vite plugin that transforms workflow code (`"use step"`/`"use workflow"` directives) in SvelteKit apps
+    </Card>
+</Cards>

package/docs/api-reference/workflow-sveltekit/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "workflow/sveltekit",
+  "pages": ["workflow-plugin"]
+}

package/docs/api-reference/workflow-sveltekit/workflow-plugin.mdx

@@ -0,0 +1,42 @@
+---
+title: workflowPlugin
+description: Configure Vite to transform workflow directives in SvelteKit.
+type: reference
+summary: Add workflowPlugin to your Vite config to enable workflow directive transformation in SvelteKit apps.
+prerequisites:
+  - /docs/getting-started/sveltekit
+---
+
+Returns the Vite plugins that transform workflow code (`"use step"`/`"use workflow"` directives) and build the workflow bundles in a SvelteKit app.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflowPlugin()` to the `plugins` array of your Vite config.
+
+```typescript title="vite.config.ts" lineNumbers
+import { sveltekit } from "@sveltejs/kit/vite";
+import { defineConfig } from "vite";
+import { workflowPlugin } from "workflow/sveltekit"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [sveltekit(), workflowPlugin()], // [!code highlight]
+});
+```
+
+## API signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `WorkflowPluginOptions` | Optional. Configures the workflow build. |
+
+#### WorkflowPluginOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `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. |
+
+### Returns
+
+Returns an array of Vite `Plugin` objects. Spread or pass the array directly to the `plugins` option of your Vite config. Vite flattens nested plugin arrays automatically.

package/docs/api-reference/workflow-vite/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "workflow/vite"
+description: Vite plugin for automatic workflow bundling in Vite + Nitro apps.
+type: overview
+summary: Explore the Vite plugin for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/vite
+---
+
+Vite integration for Workflow SDK. It wraps the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module as a Vite plugin, for apps using Nitro's Vite plugin (`nitro/vite`).
+
+## Functions
+
+<Cards>
+    <Card title="workflow()" href="/docs/api-reference/workflow-vite/workflow">
+        Vite plugin that transforms workflow code (`"use step"`/`"use workflow"` directives) and configures the Nitro server
+    </Card>
+</Cards>

package/docs/api-reference/workflow-vite/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "workflow/vite",
+  "pages": ["workflow"]
+}

package/docs/api-reference/workflow-vite/workflow.mdx

@@ -0,0 +1,48 @@
+---
+title: workflow
+description: Configure Vite and Nitro to transform workflow directives.
+type: reference
+summary: Add the workflow plugin to your Vite config to enable workflow directive transformation in Vite + Nitro apps.
+prerequisites:
+  - /docs/getting-started/vite
+---
+
+Returns the Vite plugins that transform workflow code (`"use step"`/`"use workflow"` directives) and configure the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module on the Nitro server. It is designed to be used alongside `nitro()` from `nitro/vite`, which provides the server framework for API routes and deployment.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflow()` to the `plugins` array of your Vite config, together with `nitro()`.
+
+```typescript title="vite.config.ts" lineNumbers
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { workflow } from "workflow/vite"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [nitro(), workflow()], // [!code highlight]
+  nitro: {
+    serverDir: "./",
+  },
+});
+```
+
+## API signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `ModuleOptions` | Optional. Forwarded to the `workflow/nitro` module as its module options. |
+
+#### ModuleOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dirs` | `string[]` | — | Directories to scan for workflows and steps. By default, the `workflows/` directory is scanned from the project root and all layer source directories. |
+| `typescriptPlugin` | `boolean` | `false` | Adds the `workflow` TypeScript plugin to the generated `tsconfig.json` for integrated development environment (IDE) IntelliSense. |
+| `runtime` | `string` | — | Node.js runtime version for Vercel Functions (for example, `'nodejs22.x'` or `'nodejs24.x'`). Only applies when deploying to Vercel. |
+| `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. |
+
+### Returns
+
+Returns an array of Vite `Plugin` objects. Spread or pass the array directly to the `plugins` option of your Vite config. Vite flattens nested plugin arrays automatically.