Astro

Create your Astro project

Create an Astro project in a new directory named my-workflow-app:

npm create astro@latest my-workflow-app -- --template minimal --install --yes

Enter the newly made directory:

cd my-workflow-app

Install workflow

npm i workflow

Configure Astro

Add workflow() to your Astro config. This enables usage of the "use workflow" and "use step" directives.

// @ts-check
import { defineConfig } from "astro/config";
import { workflow } from "workflow/astro";

// https://astro.build/config
export default defineConfig({
  integrations: [workflow()],
});

workflow() accepts an options object:

{
  "compilerOptions": {
    // ... rest of your TypeScript config
    "plugins": [
      {
        "name": "workflow"
      }
    ]
  }
}

Create your first workflow

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 first review 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.

Create your workflow steps

Define the 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}`);

  // Full Node.js access - database calls, APIs, etc.
  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) {
  // By default, steps will be retried for unhandled errors
   throw new Error("Retryable!");
  }
}

async function sendOnboardingEmail(user: { id: string; email: string}) {
  "use step";

  if (!user.email.includes("@")) {
    // To skip retrying, throw a FatalError instead
    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 workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
• 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.

Create your route handler

To invoke your new workflow, we'll have to add your workflow to a POST API route handler, src/pages/api/signup.ts with the following code:

import type { APIRoute } from "astro";
import { start } from "workflow/api";
import { handleUserSignup } from "../../workflows/user-signup";

export const POST: APIRoute = async ({ request }: { request: Request }) => {
  const { email } = await request.json();

  // Executes asynchronously and doesn't block your app
  await start(handleUserSignup, [email]);
  return Response.json({
    message: "User signup workflow started",
  });
};

export const prerender = false; // Don't prerender this page since it's an API route

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