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

package/docs/getting-started/python.mdx

@@ -10,48 +10,46 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="Set up Workflow in this Python project. In `pyproject.toml`, add `requires-python = &quot;&gt;=3.12&quot;` and `dependencies = [&quot;vercel-workflow&quot;]` under `[project]`, then add `[[tool.vercel.workflows]]` with `entrypoint = &quot;app.workflows:wf&quot;`. Create `app/workflow.py` with `from vercel import workflow` and `wf = workflow.Workflows()`. Create `app/steps/generate_draft.py`, import `wf`, and define async step functions such as `generate_draft` and `summarize_draft`, decorating each with `@wf.step`. Then create `app/workflows/ai_content_workflow.py`, import `wf` and those step functions, and define `@wf.workflow async def ai_content_workflow(*, topic: str)` to orchestrate them and return the result. In `app/workflows/__init__.py`, export `wf` and import the workflow module so its definitions are registered. From server-side code, start it with `await workflow.start(ai_content_workflow, topic=...)`; use the returned `Run` to access its ID, check its status, or await its return value. Where the workflow needs a durable delay, use `await workflow.sleep(timedelta(days=7))` after importing `timedelta` from `datetime`. Where it needs an external approval event, define a Pydantic model that also extends `workflow.BaseHook`, wait with `.wait(token=...)`, and resume it from server-side code with `.resume(token)`."
+/>
+
 <Callout type="warn">
-The Python SDK is currently in **beta**. APIs and behavior may change. For the latest documentation and updates, see the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflow/python?language=py).
+The Python SDK is currently in **beta**. APIs and behavior may change.
 </Callout>
 
-You can build durable workflows in Python using the [`vercel` Python SDK](https://pypi.org/project/vercel/). Your workflow code can pause, resume, and maintain state, just like the JavaScript and TypeScript Workflow SDK.
-
-## Getting Started
+You can build durable workflows in Python using the [`vercel-workflow` SDK](https://pypi.org/project/vercel-workflow/). Your workflow code can pause, resume, and maintain state, just like the JavaScript and TypeScript Workflow SDK.
 
-Install the `vercel` package:
+## Getting started
 
-```bash filename="Terminal"
-pip install vercel
-```
+Add the `vercel-workflow` package and workflow entrypoint to `pyproject.toml`:
 
-Configure `experimentalServices` in your `vercel.json`:
+```toml filename="pyproject.toml"
+[project]
+requires-python = ">=3.12"
+dependencies = ["vercel-workflow"]
 
-```json filename="vercel.json"
-{
-  "experimentalServices": {
-    "ai_content_workflow": {
-      "type": "worker",
-      "entrypoint": "app/workflows/ai_content_workflow.py",
-      "topics": ["__wkf_*"]
-    }
-  }
-}
+[[tool.vercel.workflows]]
+entrypoint = "app.workflows:wf"
 ```
 
+The workflow `entrypoint` uses the `module:object` format and points to the exported `Workflows` registry.
+
 ## Workflows
 
 A workflow is a stateful function that coordinates multi-step logic over time. Create a `Workflows` instance and use the `@wf.workflow` decorator to mark a function as durable:
 
-```python filename="app/workflow.py" {3}
+```python filename="app/workflow.py"
 from vercel import workflow
 
-wf = workflow.Workflows()
+wf = workflow.Workflows()  # [!code highlight]
 ```
 
-```python filename="app/workflows/ai_content_workflow.py" {3}
+```python filename="app/workflows/ai_content_workflow.py"
 from app.workflow import wf
+from app.steps.generate_draft import generate_draft, summarize_draft
 
-@wf.workflow
+@wf.workflow  # [!code highlight]
 async def ai_content_workflow(*, topic: str):
     draft = await generate_draft(topic=topic)
     summary = await summarize_draft(draft=draft)
@@ -62,21 +60,30 @@ async def ai_content_workflow(*, topic: str):
     }
 ```
 
+Export the registry from the workflow package and import the module containing your workflow so its definitions are registered:
+
+```python filename="app/workflows/__init__.py"
+from app.workflow import wf
+from app.workflows import ai_content_workflow
+
+__all__ = ["ai_content_workflow", "wf"]
+```
+
 Under the hood, the workflow compiles into a route that orchestrates execution. All inputs and outputs are recorded in an event log. If a deploy or crash happens, the system replays execution deterministically from where it stopped.
 
 ## Steps
 
 A step is a stateless function that runs a unit of durable work inside a workflow. Use `@wf.step` to mark a function as a step:
 
-```python filename="app/steps/generate_draft.py" {4,8}
+```python filename="app/steps/generate_draft.py"
 import random
 from app.workflow import wf
 
-@wf.step
+@wf.step  # [!code highlight]
 async def generate_draft(*, topic: str):
     return await ai_generate(prompt=f"Write a blog post about {topic}")
 
-@wf.step
+@wf.step  # [!code highlight]
 async def summarize_draft(*, draft: str):
     summary = await ai_summarize(text=draft)
 
@@ -87,20 +94,44 @@ async def summarize_draft(*, draft: str):
     return summary
 ```
 
-Each step compiles into an isolated route. While the step executes, the workflow suspends without consuming resources. When the step completes, the workflow resumes automatically where it left off.
+Each step executes separately from the workflow orchestrator. While the step executes, the workflow suspends without consuming resources. When the step completes, the workflow resumes automatically where it left off.
+
+## Starting a workflow
+
+Call `workflow.start()` from server-side code to start a workflow. It returns a `Run` that you can use to identify the run, check its status, and wait for its result:
+
+```python filename="app/api/generate.py"
+from app.workflows.ai_content_workflow import ai_content_workflow
+from vercel import workflow
+
+@app.post("/api/generate")
+async def generate_content(*, topic: str):
+    run = await workflow.start(ai_content_workflow, topic=topic)  # [!code highlight]
+
+    print(run.run_id)
+    print(await run.status())  # [!code highlight]
+
+    # Wait until the workflow completes and return its result.
+    return await run.return_value()  # [!code highlight]
+```
+
+Starting a workflow only waits until the run has been created and queued. Await `return_value()` to wait for the workflow to finish, or save its `run_id` and recreate the handle later with `workflow.Run(run_id)`.
 
 ## Sleep
 
 Sleep pauses a workflow for a specified duration without consuming compute resources:
 
-```python filename="app/workflows/ai_refine.py" {7}
+```python filename="app/workflows/ai_refine.py"
+from datetime import timedelta
+
+from app.workflow import wf
 from vercel import workflow
 
 @wf.workflow
 async def ai_refine_workflow(*, draft_id: str):
     draft = await fetch_draft(draft_id)
 
-    await workflow.sleep("7 days")  # Wait 7 days to gather more signals.
+    await workflow.sleep(timedelta(days=7))  # Wait 7 days to gather more signals.  # [!code highlight]
 
     refined = await refine_draft(draft)
 
@@ -110,7 +141,31 @@ async def ai_refine_workflow(*, draft_id: str):
     }
 ```
 
-The sleep call pauses the workflow and consumes no resources. The workflow resumes automatically when the time expires.
+The parameter accepts four forms:
+
+| Form | Description | Example |
+| --- | --- | --- |
+| `str` | Human-readable duration string | `"2 days"`, `"1w"`, `"1h 30m"` |
+| `int` or `float` | Seconds from now | `5` (5 seconds) |
+| `datetime.timedelta` | Duration from now | `timedelta(days=7)` |
+| `datetime.datetime` | Absolute wake-up time (must be timezone-aware) | `datetime(2025, 1, 1, tzinfo=UTC)` |
+
+The string form accepts one or more `<value><unit>` pairs. Supported units:
+
+| Duration | Unit |
+| --- | --- |
+| Milliseconds | `ms` |
+| Seconds | `s`, `second`, `seconds` |
+| Minutes | `m`, `minute`, `minutes` |
+| Hours | `h`, `hour`, `hours` |
+| Days | `d`, `day`, `days` |
+| Weeks | `w`, `week`, `weeks` |
+
+<Callout>
+`sleep()` must be called from the workflow body, not from inside a step. Calling it from a step raises a `RuntimeError`.
+</Callout>
+
+The sleep consumes no resources. The workflow resumes automatically when the time expires.
 
 ## Hooks
 
@@ -118,13 +173,17 @@ A hook lets a workflow wait for external events such as user actions, webhooks,
 
 Define a hook model with Pydantic and `workflow.BaseHook`:
 
-```python filename="app/workflows/approval.py" {3,14}
+```python filename="app/workflows/approval.py"
+import typing
+
+import pydantic
+from app.workflow import wf
 from vercel import workflow
 
-class Approval(BaseModel, workflow.BaseHook):
+class Approval(pydantic.BaseModel, workflow.BaseHook):  # [!code highlight]
     """Human approval for AI-generated drafts"""
 
-    decision: Literal["approved", "changes"]
+    decision: typing.Literal["approved", "changes"]
     notes: str | None = None
 
 @wf.workflow
@@ -132,7 +191,7 @@ async def ai_approval_workflow(*, topic: str):
     draft = await generate_draft(topic=topic)
 
     # Wait for human approval events
-    async for event in Approval.wait(token="draft-123"):
+    async for event in Approval.wait(token="draft-123"):  # [!code highlight]
         if event.decision == "approved":
             await publish_draft(draft)
             break
@@ -143,22 +202,58 @@ async def ai_approval_workflow(*, topic: str):
 
 Resume the workflow when data arrives:
 
-```python filename="app/api/resume.py" {5}
+```python filename="app/api/resume.py"
+from app.workflows.approval import Approval
+
 @app.post("/api/resume")
-async def resume(approval: Approval):
+async def resume(approval: Approval):  # [!code highlight]
     """Resume the workflow when an approval is received"""
 
-    await approval.resume("draft-123")
+    await approval.resume("draft-123")  # [!code highlight]
     return {"ok": True}
 ```
 
 When a hook receives data, the workflow resumes automatically. You don&apos;t need polling, message queues, or manual state management.
 
-## Learn More
+## Streaming
+
+Steps can stream progress while a workflow is running. Get the run&apos;s writable stream inside a step, write values to it, and close it when no more values will be sent:
+
+```python filename="app/workflows/streaming.py"
+from app.workflow import wf
+from vercel import workflow
+
+@wf.step
+async def write_progress():
+    writable = workflow.get_writable()  # [!code highlight]
+
+    for message in ["Drafting", "Reviewing", "Complete"]:
+        await writable.write(message)  # [!code highlight]
+
+    await writable.close()
+
+@wf.workflow
+async def streaming_workflow():
+    await write_progress()
+```
+
+Read the values from the returned `Run` as they arrive:
+
+```python filename="app/api/stream.py"
+from app.workflows.streaming import streaming_workflow
+from vercel import workflow
+
+@app.post("/api/stream")
+async def stream_progress():
+    run = await workflow.start(streaming_workflow)
+
+    async for message in run.readable():  # [!code highlight]
+        print(message)
+```
 
-For comprehensive documentation, examples, and the latest updates, visit the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflow/python).
+Streams are not closed automatically. Close the writable in the last step that writes to it so readers know when the stream is complete.
 
-## Next Steps
+## Next steps
 
 - Learn more about the [Foundations](/docs/foundations).
 - Check [Errors](/docs/errors) if you encounter issues.

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

@@ -0,0 +1,33 @@
+---
+title: React Router
+description: Run durable workflows in a React Router framework-mode app using Nitro.
+type: overview
+summary: Choose your React Router version and connect React Router, Nitro, and Workflow SDK.
+related:
+  - /docs/getting-started/nitro
+  - /docs/getting-started/vite
+  - /docs/foundations/workflows-and-steps
+---
+
+React Router framework mode builds the browser application and its server-rendering code, but it still needs a server to receive requests. [Nitro](https://v3.nitro.build) provides that server. Workflow SDK integrates with Nitro to add the durable workflow routes and build artifacts.
+
+The three pieces share one Vite build:
+
+1. **React Router** builds your routes, loaders, actions, and browser assets.
+2. **Nitro** runs the React Router request handler and any routes in `server/routes`.
+3. **Workflow SDK** finds files with `"use workflow"` and `"use step"`, then adds its runtime routes to Nitro.
+
+Choose the guide that matches your React Router major version:
+
+<AutoCards />
+
+<Callout>
+  These guides require **Nitro v3**. Nitro v2 does not provide the Vite
+  environment integration used by this setup.
+</Callout>
+
+## What the bridge does
+
+The setup adds a small `server/ssr.ts` file. It turns React Router's generated server build into a standard Fetch API handler that Nitro can run. The Vite config then points Nitro's server and public output at the same `build` directory React Router uses.
+
+This is configuration in your application, not a separate React Router adapter. Your React Router routes remain React Router routes, while Nitro owns the HTTP server and Workflow SDK uses Nitro's lifecycle and routing.

package/docs/getting-started/react-router/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "React Router",
+  "pages": ["v7", "v8"],
+  "defaultOpen": true
+}

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

@@ -0,0 +1,237 @@
+---
+title: React Router v7
+description: Add durable workflows to a React Router v7 framework-mode app using Nitro v3.
+type: guide
+summary: Enable the Vite Environment API and configure React Router v7, Nitro v3, and Workflow SDK.
+prerequisites:
+  - /docs/getting-started/react-router
+related:
+  - /docs/getting-started/nitro
+  - /docs/foundations/workflows-and-steps
+---
+
+This guide starts with an existing React Router v7 framework-mode app. It is verified with v7.18.1; if your config does not recognize `v8_viteEnvironmentApi`, update to the latest v7 release.
+
+<Steps>
+
+<Step>
+
+## Install Nitro and Workflow SDK
+
+<Tabs items={["npm", "pnpm", "bun", "yarn"]} defaultValue="pnpm">
+
+<Tab value="npm">
+
+```bash
+npm install nitro workflow
+```
+
+</Tab>
+
+<Tab value="pnpm">
+
+```bash
+pnpm add nitro workflow
+```
+
+</Tab>
+
+<Tab value="bun">
+
+```bash
+bun add nitro workflow
+```
+
+</Tab>
+
+<Tab value="yarn">
+
+```bash
+yarn add nitro workflow
+```
+
+</Tab>
+
+</Tabs>
+
+This integration requires Nitro v3.
+
+</Step>
+
+<Step>
+
+## Enable the Vite Environment API
+
+React Router v7 keeps the Vite Environment API behind a future flag. Enable the required flag and set an explicit build directory:
+
+```typescript title="react-router.config.ts" lineNumbers
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: true,
+  buildDirectory: "build", // [!code highlight]
+  future: {
+    v8_viteEnvironmentApi: true, // [!code highlight]
+  },
+} satisfies Config;
+```
+
+</Step>
+
+<Step>
+
+## Create the React Router server handler
+
+Create `server/ssr.ts`:
+
+```typescript title="server/ssr.ts" lineNumbers
+import { createRequestHandler } from "react-router";
+
+export default {
+  fetch: createRequestHandler(
+    () => import("virtual:react-router/server-build"),
+    import.meta.env.MODE,
+  ),
+};
+```
+
+This adapts React Router's generated server build to the Fetch API handler Nitro expects.
+
+</Step>
+
+<Step>
+
+## Configure Vite
+
+Update `vite.config.ts`:
+
+```typescript title="vite.config.ts" lineNumbers
+import { reactRouter } from "@react-router/dev/vite";
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { workflow } from "workflow/vite";
+import reactRouterConfig from "./react-router.config";
+
+export default defineConfig({
+  plugins: [
+    reactRouter(),
+    nitro({
+      serverDir: "./server",
+      output: {
+        dir: reactRouterConfig.buildDirectory,
+        serverDir: `${reactRouterConfig.buildDirectory}/server`,
+        publicDir: `${reactRouterConfig.buildDirectory}/client`,
+      },
+    }),
+    workflow({ dirs: ["workflows"] }),
+  ],
+  environments: {
+    ssr: {
+      build: {
+        rollupOptions: {
+          input: "./server/ssr.ts",
+        },
+      },
+    },
+  },
+});
+```
+
+Keep `dirs: ["workflows"]` so subsequent builds do not scan generated files under `build`. Place `reactRouter()` before `nitro()` in the plugin array.
+
+</Step>
+
+<Step>
+
+## Create a workflow
+
+Create `workflows/greeting.ts`:
+
+```typescript title="workflows/greeting.ts" lineNumbers
+export async function greetingWorkflow(name: string) {
+  "use workflow";
+
+  return greet(name);
+}
+
+async function greet(name: string) {
+  "use step";
+
+  return `Hello, ${name}!`;
+}
+```
+
+</Step>
+
+<Step>
+
+## Start the workflow from a Nitro route
+
+Create `server/routes/api/greeting.post.ts`:
+
+```typescript title="server/routes/api/greeting.post.ts" lineNumbers
+import { defineHandler } from "nitro";
+import { start } from "workflow/api";
+import { greetingWorkflow } from "../../../workflows/greeting";
+
+export default defineHandler(async (event) => {
+  const { name } = (await event.req.json()) as { name: string };
+  const run = await start(greetingWorkflow, [name]);
+
+  return { runId: run.runId };
+});
+```
+
+React Router continues to handle your application routes. Nitro handles this server route at `POST /api/greeting`, as well as Workflow SDK's internal routes.
+
+</Step>
+
+<Step>
+
+## Run the app
+
+Start the development server:
+
+```bash
+pnpm vite dev
+```
+
+Then start a workflow:
+
+```bash
+curl -X POST \
+  -H "content-type: application/json" \
+  -d '{"name":"Workflow"}' \
+  http://localhost:3000/api/greeting
+```
+
+Build and start the production server:
+
+```bash
+pnpm vite build
+node ./build/server/index.mjs
+```
+
+You can inspect local runs with `pnpm workflow web`.
+
+</Step>
+
+</Steps>
+
+## Troubleshooting
+
+### Vite reports an invalid SSR input or `path.replace is not a function`
+
+Set `future.v8_viteEnvironmentApi` to `true` in `react-router.config.ts`.
+
+### React Router pages return 404
+
+Check that the `ssr` environment input points to `./server/ssr.ts`.
+
+### A second build tries to compile files under `build/server`
+
+Use `workflow({ dirs: ["workflows"] })`, remove the existing `build` directory once, and rebuild.
+
+### `vite build` finishes output but does not exit
+
+Use `workflow@5.0.0` or later with Nitro v3.