Farm.js

Durable Workflows

A durable workflow is a function whose progress is saved after every step. It can sleep for days, wait for an approval or a webhook, and pick up where it stopped after a crash or a redeploy, without running finished steps again.

Farm runs them two ways:

  • Workflow SDK runs workflows inside your app's server. You mark async functions with "use workflow" and "use step" and start them from API routes.
  • Jobs with Inngest keeps each run in Inngest, which calls your app for every step. Farm's Jobs integration starts runs and reads their status through api.jobs.

Jobs can also hand a run to Trigger.dev, whose tasks run on its own servers.

When to use one

NeedUse
Short best-effort work after a responseafter()
Call one API route on a scheduleCron
Background tasks with retries, status, and cancellation, run by your app, Trigger.dev, or InngestJobs
Multi-step work that sleeps, waits for an event or a webhook, and survives restartsDurable workflows (this page)
An agent run that pauses for a person's approvalDurable agents

Choose an approach

Workflow SDKJobs with Inngest
Where steps runYour serverYour server, called by Inngest
Where runs are stored.workflow-data on a Node server, or VercelInngest
farm devRuns don't executeRuns with the Inngest dev server
Wait for an eventcreateHook() and resumeHook()step.waitForEvent()
Start and read runsstart() and getRun()api.jobs.<task>.trigger() and .status()
Service in productionNone on a Node server, Vercel Queues on VercelInngest Cloud or a self-hosted Inngest server

Workflow SDK

Workflow SDK compiles workflow functions at build time and adds its own routes to Farm's server.

Workflows run in production builds. farm dev records a run but doesn't execute it, so try workflows with farm build && farm start. Limits lists the other places they don't run yet.

How it fits together

PieceWhereWhat it does
Workflows and stepssrc/workflows/*.tsThe durable functions
The pluginfarm.config.tsCompiles workflow files and adds Workflow SDK's routes to the build
The startup hooksrc/instrumentation.tsResumes unfinished runs when the server starts
API routessrc/app/api/**/route.tsStart runs, read their status, and resume them

Workflow SDK serves its own routes under /.well-known/workflow/v1/. Its queue calls them to run each step, and webhooks arrive there.

Install

pnpm add workflow
pnpm add -D @workflow/rollup

pnpm runs a dependency's build script only when it's allowed. Allow the two that Workflow SDK brings, next to the entries Farm's templates already list:

pnpm-workspace.yaml
allowBuilds:
  "@swc/core": true
  cbor-extract: true

Add the folder where runs are stored to .gitignore:

.gitignore
.workflow-data

Configure Farm

farm.config.ts
import { defineConfig } from "@farm.js/core";
import { definePlugin } from "@farm.js/core/plugin";
import { workflowTransformPlugin } from "@workflow/rollup";

const workflowSdk = definePlugin({
  name: "workflow-sdk",
  build: {
    configure(nitroConfig) {
      return {
        ...nitroConfig,
        modules: [...(nitroConfig.modules ?? []), "workflow/nitro"],
        workflow: { dirs: ["src"] },
      };
    },
  },
});

export default defineConfig({
  vite: { plugins: [workflowTransformPlugin()] },
  plugins: [workflowSdk],
});

The Vite plugin compiles "use workflow" and "use step" functions. The plugin's build.configure hook adds Workflow SDK's Nitro module, which generates the workflow routes, and limits its file scan to src. Naming the module as a string, instead of importing it, keeps build-only code out of the server bundle.

Resume runs on startup

src/instrumentation.ts
import type { FarmInstrumentationContext } from "@farm.js/core/instrumentation";

export async function register(context: FarmInstrumentationContext) {
  if (context.runtime !== "nodejs") return;

  const { getWorld } = await import("workflow/runtime");
  const world = await getWorld();
  await world.start?.();
}

Without this hook, a run that was sleeping or waiting when the server stopped stays running after a restart. If the app already has an instrumentation file, add these lines to its register function.

Write a workflow

src/workflows/welcome.ts
import { sleep } from "workflow";

export async function welcome(email: string) {
  "use workflow";

  const user = await createUser(email);
  await sleep("5s");
  await sendWelcomeEmail(user.email);

  return { email: user.email, status: "welcomed" };
}

async function createUser(email: string) {
  "use step";
  return { email };
}

async function sendWelcomeEmail(email: string) {
  "use step";
  console.log(`Sent welcome email to ${email}`);
}

The workflow function decides what happens next; each step is a checkpoint. When a step finishes, Workflow SDK saves its result, and a replay after a restart reuses it instead of running the step again. Steps run as ordinary server code, so database calls, SDK calls, and process.env belong there. Workflow functions are replayed in a sandbox and must be deterministic.

sleep() accepts a duration such as "5s" or "7d". A sleeping run uses no compute.

Start a run and read its status

src/app/api/signup/route.ts
import { start } from "workflow/api";
import { welcome } from "../../../workflows/welcome";

export async function POST(request: Request) {
  const { email } = await request.json();
  const run = await start(welcome, [email]);
  return Response.json({ runId: run.runId }, { status: 202 });
}
src/app/api/runs/route.ts
import { getRun } from "workflow/api";
import { WorkflowRunNotFoundError } from "workflow/errors";

export async function GET(request: Request) {
  const runId = new URL(request.url).searchParams.get("id");
  if (!runId) return Response.json({ error: "Pass ?id=<runId>." }, { status: 400 });

  const run = getRun(runId);
  try {
    const status = await run.status;
    const result = status === "completed" ? await run.returnValue : undefined;
    return Response.json({ runId, status, result });
  } catch (error) {
    if (WorkflowRunNotFoundError.is(error)) {
      return Response.json({ error: "Run not found." }, { status: 404 });
    }
    throw error;
  }
}

Build, start, and try it:

farm build && farm start

curl -X POST http://localhost:3000/api/signup \
  -H "content-type: application/json" -d '{"email":"ada@example.com"}'
# {"runId":"wrun_..."}

curl "http://localhost:3000/api/runs?id=wrun_..."
# {"runId":"wrun_...","status":"completed","result":{"email":"ada@example.com","status":"welcomed"}}

A run's status is pending, running, completed, failed, or cancelled. Stop the server while a run sleeps and start it again: the run finishes after the restart.

Wait for an event

A hook pauses a run until your app resumes it. Give the hook a token you can rebuild later, such as one derived from an order id.

src/workflows/refund.ts
import { createHook } from "workflow";

export async function refund(orderId: string) {
  "use workflow";

  const approval = createHook<{ approved: boolean }>({ token: `refund:${orderId}` });
  const { approved } = await approval;

  if (!approved) return { orderId, status: "rejected" };
  await issueRefund(orderId);
  return { orderId, status: "refunded" };
}

async function issueRefund(orderId: string) {
  "use step";
  console.log(`Refunded order ${orderId}`);
}
src/app/api/refunds/route.ts
import { start } from "workflow/api";
import { refund } from "../../../workflows/refund";

export async function POST(request: Request) {
  const { orderId } = await request.json();
  const run = await start(refund, [orderId]);
  return Response.json({ runId: run.runId }, { status: 202 });
}
src/app/api/refunds/approve/route.ts
import { resumeHook } from "workflow/api";
import { HookNotFoundError } from "workflow/errors";

export async function POST(request: Request) {
  const { orderId, approved } = await request.json();
  // Check that the caller may approve refunds before resuming the run.
  try {
    await resumeHook(`refund:${orderId}`, { approved: approved === true });
  } catch (error) {
    if (HookNotFoundError.is(error)) {
      return Response.json({ error: "No refund is waiting for approval." }, { status: 404 });
    }
    throw error;
  }
  return new Response(null, { status: 204 });
}

Anyone who can call the approve route can approve a refund, so check the caller's session there before resuming. resumeHook throws HookNotFoundError when no run is waiting on the token, for example after the refund was already decided.

Receive a webhook

A webhook gives one run its own URL. Another service calls it, and the run resumes with that request.

src/workflows/payment.ts
import { createWebhook } from "workflow";

export async function awaitPayment(orderId: string) {
  "use workflow";

  const webhook = createWebhook();
  await sendPaymentLink(orderId, webhook.token);

  const request = await webhook;
  const event = await request.json();
  return { orderId, paid: event.status === "paid" };
}

async function sendPaymentLink(orderId: string, token: string) {
  "use step";
  const callbackUrl = `${process.env.SITE_URL}/.well-known/workflow/v1/webhook/${token}`;
  console.log(`Payment callback for ${orderId}: ${callbackUrl}`);
}
src/app/api/payments/route.ts
import { start } from "workflow/api";
import { awaitPayment } from "../../../workflows/payment";

export async function POST(request: Request) {
  const { orderId } = await request.json();
  const run = await start(awaitPayment, [orderId]);
  return Response.json({ runId: run.runId }, { status: 202 });
}

The webhook route answers 202 for a token a run is waiting on and 404 for any other token. Off Vercel, webhook.url points at http://localhost:<port>, so the step builds the public URL from SITE_URL, your app's public origin, and the token.

Where runs are stored

Workflow SDK stores runs and queues steps through a world.

  • Node server. The Local World keeps runs in .workflow-data in the directory the server starts from. Keep that folder on a persistent disk, and run one server process per folder. Runs started in farm dev also land there, stay pending, and run the next time farm start boots from the same folder.
  • Vercel. Workflow SDK uses the Vercel World, backed by Vercel Queues.

Other worlds, such as @workflow/world-postgres selected with WORKFLOW_TARGET_WORLD, are loaded by package name when the server starts, so Farm's build output doesn't include them. Run the server from the app directory, where node_modules has the world installed.

Deploy

Node. farm build writes a server to .farm/.output that runs on its own, without node_modules. Start it with farm start or node .farm/.output/server/index.mjs, and set SITE_URL if workflows create webhooks.

Vercel. Set the target:

farm.config.ts
export default defineConfig({
  vite: { plugins: [workflowTransformPlugin()] },
  plugins: [workflowSdk],
  deploy: { target: "vercel" },
});

The build puts /.well-known/workflow/v1/flow in its own function, with the longest duration the plan allows and a Vercel Queues trigger. The rest of the app stays in one function.

Limits

  • farm dev. Runs are recorded but never execute. build.configure runs only in production builds, so the workflow routes don't exist in development.
  • Cloudflare. A cloudflare-module build fails to start with No such module "node:http", imported by Workflow SDK.
  • experimental.serverComponents: { mode: "rsc" }. The RSC build doesn't run build.configure, so the workflow routes are missing and runs stay pending. The default and islands modes work.

Jobs with Inngest

Inngest keeps each run's state and calls your app over HTTP to run the next step, so a run survives restarts and redeploys of the app. This builds the same refund flow as Wait for an event with the Inngest SDK's steps.

Install

pnpm add @farm.js/jobs inngest

With pnpm, also allow the build script of protobufjs, which the Inngest SDK brings:

pnpm-workspace.yaml
allowBuilds:
  protobufjs: true

Write the function

src/inngest/client.ts
import { Inngest } from "inngest";

export const inngestClient = new Inngest({ id: "shop" });
src/inngest/refund.ts
import { inngestClient } from "./client";

export const refundOrder = inngestClient.createFunction(
  { id: "refund-order", triggers: [{ event: "farm/refund-order" }] },
  async ({ event, step }) => {
    const orderId: string = event.data.orderId;

    const decision = await step.waitForEvent("wait-for-approval", {
      event: "shop/refund.decided",
      match: "data.orderId",
      timeout: "7d",
    });
    if (!decision?.data.approved) return { orderId, status: "rejected" };

    await step.run("issue-refund", () => {
      console.log(`Refunded order ${orderId}`);
    });
    return { orderId, status: "refunded" };
  },
);

Jobs sends an event named farm/<task id>, so the function listens for farm/refund-order. step.waitForEvent() pauses the run until a shop/refund.decided event with the same data.orderId arrives, and returns null when the timeout passes first. An approval for another order doesn't resume this run. step.run() runs its callback once and saves the result for the function's later calls.

Serve it from the app

src/app/api/inngest/route.ts
import { serve } from "inngest/edge";
import { inngestClient } from "../../../inngest/client";
import { refundOrder } from "../../../inngest/refund";

const handler = serve({ client: inngestClient, functions: [refundOrder] });

export { handler as GET, handler as POST, handler as PUT };

Inngest calls this route to register the function and to run each step. In production, the SDK checks each request's signature with INNGEST_SIGNING_KEY.

Trigger it with Jobs

src/lib/jobs.ts
import { defineTasks, task } from "@farm.js/jobs";

export const tasks = defineTasks({
  refundOrder: task({
    id: "refund-order",
    // Inngest runs the function in src/inngest/refund.ts. This callback only types its input and output.
    async run(input: { orderId: string }) {
      return { orderId: input.orderId, status: "refunded" as "refunded" | "rejected" };
    },
  }),
});
src/lib/integrations.ts
import { inngest, jobs } from "@farm.js/jobs";
import { tasks } from "./jobs";

export const appIntegrations = {
  jobs: jobs({
    runtime: inngest({
      eventKey: process.env.INNGEST_EVENT_KEY,
      signingKey: process.env.INNGEST_SIGNING_KEY,
      eventBaseUrl: process.env.INNGEST_EVENT_BASE_URL,
      apiBaseUrl: process.env.INNGEST_API_BASE_URL,
    }),
    tasks,
  }),
} as const;

export type AppIntegrations = typeof appIntegrations;
farm.config.ts
import { defineConfig } from "@farm.js/core";
import { appIntegrations } from "./src/lib/integrations";

export default defineConfig({
  integrations: appIntegrations,
});
src/lib/api.server.ts
import { createIntegrations } from "@farm.js/core/client";
import type { AppIntegrations } from "./integrations";

export const { api } = createIntegrations<AppIntegrations>();
src/app/api/refunds/route.ts
import { api } from "../../../lib/api.server";

export async function POST(request: Request) {
  const { orderId } = await request.json();
  const result = await api.jobs.refundOrder.trigger({ body: { orderId } });
  if (result.error) throw result.error;
  return Response.json({ handleId: result.data!.handleId }, { status: 202 });
}
src/app/api/refunds/approve/route.ts
import { inngestClient } from "../../../../inngest/client";

export async function POST(request: Request) {
  const { orderId, approved } = await request.json();
  // Check that the caller may approve refunds before sending the decision.
  await inngestClient.send({
    name: "shop/refund.decided",
    data: { orderId, approved: approved === true },
  });
  return new Response(null, { status: 204 });
}
src/app/api/refunds/status/route.ts
import { api } from "../../../../lib/api.server";

export async function GET(request: Request) {
  const handleId = new URL(request.url).searchParams.get("handleId");
  if (!handleId) return Response.json({ error: "Pass ?handleId=<id>." }, { status: 400 });

  const result = await api.jobs.refundOrder.status({ query: { handleId } });
  if (result.error) throw result.error;
  return Response.json({ status: result.data!.status, output: result.data!.output });
}

If the app also uses Workflow SDK, add integrations to the same farm.config.ts. The task's run only gives api.jobs its input and output types; Inngest runs the function. A run waiting for its event reports running. As with the hook version, check the caller's session in the approve route before sending the decision.

Run it locally

Start the Inngest dev server and point it at the route, using your dev server's port:

npx inngest-cli@latest dev -u http://localhost:3000/api/inngest
.env
INNGEST_DEV=1
INNGEST_EVENT_KEY=local
INNGEST_SIGNING_KEY=signkey-local-0000
INNGEST_EVENT_BASE_URL=http://localhost:8288
INNGEST_API_BASE_URL=http://localhost:8288

Then run farm dev. The function is an ordinary API route, so it runs in development too. The dev server accepts these placeholder keys. It reports output as an empty string, so locally status tells you that a run finished but not what it returned. Stop and restart the app while a refund waits: the approval still resumes it, because the run lives in Inngest.

Go to production

Set INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY from your Inngest environment, remove INNGEST_DEV and the two base URLs, and sync https://<your-domain>/api/inngest in Inngest. Inngest lists the runtime's options and what it can't do, such as cancel a run.

Jobs with Trigger.dev

Trigger.dev runs tasks on its own servers. Write the task with the Trigger.dev SDK, which pauses with wait.for() and waits for a person or another system with wait.forToken(), and deploy it with Trigger.dev's CLI. Farm triggers it by task id through the same api.jobs calls; see Trigger.dev.

Jobs with local()

The Jobs local() runtime runs a task's own run in your app and retries the whole task when it fails. It has no steps, sleeps, or waits, so a retry starts over. It fits one-step background work; see Jobs.