---
title: Express
description: Set up your first durable workflow in an Express application.
type: guide
summary: Set up Workflow SDK in an Express app.
prerequisites:
  - /docs/getting-started
related:
  - /docs/foundations/workflows-and-steps
---

<CopyPrompt
  text="In this Express app, run `npm i workflow express nitro rollup` and, if using TypeScript, `npm i -D @types/express`. Create `nitro.config.ts` with `modules: [&quot;workflow/nitro&quot;]`, `vercel: { entryFormat: &quot;node&quot; }`, and `routes: { &quot;/**&quot;: { handler: &quot;./src/index.ts&quot;, format: &quot;node&quot; } }`. Add package scripts `dev: &quot;nitro dev&quot;` and `build: &quot;nitro build&quot;`. Create `workflows/user-signup.ts` with `&quot;use workflow&quot;`, `sleep`, and `&quot;use step&quot;` helpers. Add `src/index.ts` with Express JSON middleware, POST `/api/signup`, and `start(handleUserSignup, [email])` from `workflow/api`. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
/>

This guide will walk through setting up your first workflow in an Express app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.

---

<Steps>

<Step>
## Create your Express project

Start by creating a new Express project.

```bash
mkdir my-workflow-app
```

Enter the newly made directory:

```bash
cd my-workflow-app
```

Initialize the project:

```bash
npm init --y
```

### Install `workflow`, `express`, `nitro`, and `rollup`

```package-install
npm i workflow express nitro rollup
```

<Callout>
By default, Express doesn't include a build system. Nitro adds one which enables compiling workflows, runs, and deploys for development and production. Learn more about Nitro [here](https://v3.nitro.build).
</Callout>

If using TypeScript, you need to install the `@types/express` package.

```bash
npm i -D @types/express
```

### 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.

```typescript title="nitro.config.ts" lineNumbers
import { defineNitroConfig } from "nitro/config";

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

<Details>
<Summary>Setup IntelliSense for TypeScript (Optional)</Summary>

To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:

```json title="tsconfig.json" lineNumbers
{
  "compilerOptions": {
    // ... rest of your TypeScript config
    "plugins": [
      {
        "name": "workflow" // [!code highlight]
      }
    ]
  }
}
```

</Details>

### Update `package.json`

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

```json title="package.json" lineNumbers
{
  // ...
  "scripts": {
    "dev": "nitro dev",
    "build": "nitro build"
  },
  // ...
}
```

</Step>

<Step>

## Create your first workflow

Create a new file for our first workflow:

```typescript title="workflows/user-signup.ts" lineNumbers
import { sleep } from "workflow";

export async function handleUserSignup(email: string) {
  "use workflow"; // [!code highlight]

  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. The current code does the following:

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

```typescript title="workflows/user-signup.ts" lineNumbers
import { FatalError } from "workflow";

// Our workflow function defined earlier

async function createUser(email: string) {
  "use step"; // [!code highlight]

  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"; // [!code highlight]

  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"; // [!code highlight]

  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.

<Callout>
  We'll dive deeper into workflows, steps, and other ways to suspend or handle
  events in [Foundations](/docs/foundations).
</Callout>

</Step>

<Step>

## Create your route handler

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

```typescript title="src/index.ts"
import express from "express";
import { start } from "workflow/api";
import { handleUserSignup } from "../workflows/user-signup.js";

const app = express();
app.use(express.json());

app.post("/api/signup", async (req, res) => {
  const { email } = req.body;
  await start(handleUserSignup, [email]);
  return res.json({ message: "User signup workflow started" });
});

export default app;
```

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

</Step>

<Step>

## Run in development

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

```bash
npm run dev
```

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

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

Check the Express 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](/docs/observability) to inspect your workflow runs and steps in detail.

```bash
# Open the observability Web UI
npx workflow web
# or if you prefer a terminal interface, use the CLI inspect command
npx workflow inspect runs
```

![Workflow SDK Web UI](/o11y-ui.png)

</Step>

</Steps>

---

## Deploying to production

Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and need no special configuration.

<FluidComputeCallout />

Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.

## Troubleshooting

### `start()` says it received an invalid workflow function

If you see this error:

```text
'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.
```

Check both of these first:

1. The workflow function includes `"use workflow"`.
2. Your Nitro config includes the `workflow/nitro` module.

See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.

## Next steps

- Learn more about the [Foundations](/docs/foundations).
- Check [Errors](/docs/errors) if you encounter issues.
- Explore the [API Reference](/docs/api-reference).