Start by creating a new Fastify project.

Enter the newly made directory:

Initialize the project:

Install workflow, fastify and nitro

If using TypeScript, you need to install the @types/node and typescript packages

npm i -D @types/node typescript

Configure Nitro

Create a new file nitro.config.ts for your Nitro configuration with module workflow/nitro. This enables usage of the "use workflow" and "use step" directives

import { defineNitroConfig } from "nitro/config";

export default defineNitroConfig({
	modules: ["workflow/nitro"],
	vercel: { entryFormat: "node" },
	routes: {
		"/**": { handler: "./src/index.ts", format: "node" },
	},
});

Update package.json

To use the Nitro builder, update your package.json to include the following scripts:

{
  // ...
  "scripts": {
    "dev": "nitro dev",
    "build": "nitro build"
  },
  // ...
}

Create a new file for our first workflow:

import { sleep } from "workflow";

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

  const user = await createUser(email);
  await sendWelcomeEmail(user);

  await sleep("5s"); // Pause for 5s - doesn't consume any resources
  await sendOnboardingEmail(user);

  return { userId: user.id, status: "onboarded" };
}

We'll fill in those functions next, but let's take a look at this code:

• We define a workflow function with the directive "use workflow". Think of the workflow function as the orchestrator of individual steps.
• The Workflow SDK's sleep function allows us to suspend execution of the workflow without using up any resources. A sleep can be a few seconds, hours, days, or even months long.

Let's now define those missing functions:

import { FatalError } from "workflow";

// Our workflow function defined earlier

async function createUser(email: string) {
  "use step"; 
  console.log(`Creating user with email: ${email}`);
  return { id: crypto.randomUUID(), email };
}

async function sendWelcomeEmail(user: { id: string; email: string }) {
  "use step"; 
  console.log(`Sending welcome email to user: ${user.id}`);
  if (Math.random() < 0.3) {
    // Steps retry on unhandled errors
    throw new Error("Retryable!");
  }
}

async function sendOnboardingEmail(user: { id: string; email: string }) {
  "use step"; 
  if (!user.email.includes("@")) {
    // FatalError skips retries
    throw new FatalError("Invalid Email");
  }
  console.log(`Sending onboarding email to user: ${user.id}`);
}

Taking a look at this code:

• Business logic lives inside steps. When a step is invoked inside a workflow, it gets enqueued to run on a separate request while the workflow is suspended, just like sleep.
• If a step throws an error, like in sendWelcomeEmail, the step will automatically be retried until it succeeds (or hits the step's max retry count).
• Steps can throw a FatalError if an error is intentional and should not be retried.

To invoke your new workflow, we'll create both the Fastify app and a new API route handler at src/index.ts with the following code:

import Fastify from "fastify";
import { start } from "workflow/api";
import { handleUserSignup } from "../workflows/user-signup.js";

const app = Fastify({ logger: true });
app.post("/api/signup", async (req, reply) => {
  const { email } = req.body as { email: string };
  await start(handleUserSignup, [email]);
  return reply.send({ message: "User signup workflow started" });
});

// Wait for Fastify to be ready before handling requests
await app.ready();


export default (req: any, res: any) => {
  app.server.emit("request", req, res);
};

This route handler creates a POST request endpoint at /api/signup that will trigger your workflow.

To start your development server, run the following command in your terminal in the Fastify root directory:

Once your development server is running, you can trigger your workflow by running this command in the terminal:

curl -X POST --json '{"email":"hello@example.com"}' http://localhost:3000/api/signup

Check the Fastify development server logs to see your workflow execute as well as the steps that are being processed.

Additionally, you can use the Workflow SDK CLI or Web UI to inspect your workflow runs and steps in detail.

npx workflow inspect runs # add '--web' for an interactive Web based UI

Enable Fluid compute before deploying. Workflow is designed to take advantage of Fluid compute for efficient suspension and resumption. Without Fluid compute enabled, each workflow resume incurs a separate function cold start, which can result in significantly higher costs.