feat(cloudflare): add new steps limit option for Workflows (#1355)

jaaneh · web-flow · commit c8182ec81eab · 2026-03-04T15:29:24.000-05:00
diff --git a/alchemy-web/src/content/docs/providers/cloudflare/workflow.md b/alchemy-web/src/content/docs/providers/cloudflare/workflow.md
@@ -53,6 +53,22 @@ await Worker("my-worker", {
 });
 ```
 
+## Workflow Step Limits
+
+Set the maximum number of steps per workflow instance with `limits.steps`.
+
+```ts
+import { Workflow } from "alchemy/cloudflare";
+
+const workflow = Workflow("order-processing", {
+  workflowName: "order-processing",
+  className: "OrderProcessingWorkflow",
+  limits: {
+    steps: 25_000,
+  },
+});
+```
+
 ## Rename Class Name
 
 Alchemy takes care of migrations automatically when you rename the class name.
diff --git a/alchemy-web/src/content/docs/providers/cloudflare/wrangler.json.md b/alchemy-web/src/content/docs/providers/cloudflare/wrangler.json.md
@@ -75,6 +75,33 @@ const worker = await Worker("cron", {
 await WranglerJson({ worker });
 ```
 
+## With Workflow Step Limits
+
+If the Worker binds to a Workflow with `limits.steps`, that value is written to
+the `workflows[].limits.steps` field in `wrangler.json`.
+
+```ts
+import { Worker, Workflow, WranglerJson } from "alchemy/cloudflare";
+
+const workflow = Workflow("order-processing", {
+  workflowName: "order-processing",
+  className: "OrderProcessingWorkflow",
+  limits: {
+    steps: 25_000,
+  },
+});
+
+const worker = await Worker("orders", {
+  name: "orders-worker",
+  entrypoint: "./src/worker.ts",
+  bindings: {
+    ORDER_WORKFLOW: workflow,
+  },
+});
+
+await WranglerJson({ worker });
+```
+
 ## With Transform Hook
 
 The transform hook allows you to customize the wrangler.json configuration. For example, adding a custom environment variable:
diff --git a/alchemy/src/cloudflare/workflow.ts b/alchemy/src/cloudflare/workflow.ts
@@ -25,6 +25,20 @@ export interface WorkflowProps {
    * @default - bound worker script
    */
   scriptName?: string;
+  /**
+   * Limits for the workflow instance
+   */
+  limits?: {
+    /**
+     * Maximum number of steps per workflow instance.
+     *
+     * Workers Free: 1,024 (not configurable)
+     * Workers Paid: 10,000 default, configurable up to 25,000
+     *
+     * @see https://developers.cloudflare.com/workflows/reference/limits/
+     */
+    steps?: number;
+  };
   dev?: {
     /**
      * Whether to run the workflow remotely instead of locally
@@ -45,6 +59,9 @@ export type Workflow<PARAMS = unknown> = {
   workflowName: string;
   className: string;
   scriptName?: string;
+  limits?: {
+    steps?: number;
+  };
 };
 
 export function isWorkflow(binding: Binding): binding is Workflow {
@@ -77,6 +94,7 @@ export function Workflow<PARAMS = unknown>(
     workflowName,
     className,
     scriptName: props.scriptName,
+    limits: props.limits,
   };
 }
 
diff --git a/alchemy/src/cloudflare/wrangler.json.ts b/alchemy/src/cloudflare/wrangler.json.ts
@@ -403,6 +403,7 @@ async function processBindings(
         binding: bindingName,
         class_name: binding.className,
         script_name: binding.scriptName,
+        ...(binding.limits ? { limits: binding.limits } : {}),
       });
     } else if (binding.type === "d1") {
       const id =
diff --git a/alchemy/test/cloudflare/wrangler-json.test.ts b/alchemy/test/cloudflare/wrangler-json.test.ts
@@ -382,6 +382,51 @@ describe("WranglerJson Resource", () => {
       }
     });
 
+    test("with workflow step limits", async (scope) => {
+      const name = `${BRANCH_PREFIX}-test-worker-wf-limits`;
+      const tempDir = path.join(".out", "alchemy-wf-limits-test");
+      const entrypoint = path.join(tempDir, "worker.ts");
+
+      try {
+        await fs.rm(tempDir, { recursive: true, force: true });
+        await fs.mkdir(tempDir, { recursive: true });
+        await fs.writeFile(entrypoint, wfWorkerScript);
+
+        const workflow = Workflow("test-workflow-limits", {
+          className: "TestWorkflow",
+          workflowName: "test-workflow-limits",
+          limits: {
+            steps: 25000,
+          },
+        });
+
+        const worker = await Worker(name, {
+          name,
+          format: "esm",
+          entrypoint,
+          bindings: {
+            WF: workflow,
+          },
+          adopt: true,
+        });
+
+        const { spec } = await WranglerJson({ worker });
+
+        expect(spec.workflows).toHaveLength(1);
+        expect(spec.workflows?.[0]).toMatchObject({
+          name: "test-workflow-limits",
+          binding: "WF",
+          class_name: "TestWorkflow",
+          limits: {
+            steps: 25000,
+          },
+        });
+      } finally {
+        await fs.rm(tempDir, { recursive: true, force: true });
+        await destroy(scope);
+      }
+    });
+
     test("with cron triggers", async (scope) => {
       const name = `${BRANCH_PREFIX}-test-worker-cron-json`;
       const tempDir = path.join(".out", "alchemy-cron-json-test");
diff --git a/bun.lock b/bun.lock
diff --git a/package.json b/package.json
