Deploy and Run Your First Workflow

You can read docs about durable execution all day, but it won't click until you see it happen. This lesson gets you to that moment in 15 minutes.

Outcome

Deploy the workflow builder, run Hello World, and see the API return instantly while work continues in the background.

Fast Track

1. Click Deploy to provision Neon + create your repo
2. Clone, link, pull env, run pnpm dev
3. Click Run on Hello World workflow, check Network tab for instant response

Deploy the Visual Workflow Builder

One click provisions everything — Neon database, environment variables, your own repo.

After deploy completes, you'll have:

• A live workflow builder at your Vercel URL
• A GitHub repo with the full source
• A Neon Postgres database connected and ready

Set Up Local Development

Clone your repo so you can build plugins locally.

1. Install Vercel CLI (if you don't have it):

npm i -g vercel

2. Clone your repo:

git clone https://github.com/YOUR_USERNAME/workflow-builder-starter
cd workflow-builder-starter
pnpm install

3. Link to your Vercel project:

vercel link

Select your project when prompted.

4. Pull environment variables:

vercel env pull .env.local

This pulls DATABASE_URL from your Vercel project into .env.local (the standard Next.js local env file).

5. Push database schema:

The starter uses Drizzle ORM for database access. This command creates the tables your app needs:

pnpm db:push

6. Start the dev server:

pnpm dev

Open http://localhost:3000.

Hands-on Exercise

1. You'll see a canvas with two nodes: Manual Trigger → Hello World
2. Click Run in the toolbar
3. Open DevTools Network tab

Try It

Open Network tab and run the workflow. You should see:

POST /api/workflow/abc123/execute 200 142ms

Response:

{ "executionId": "exec_xyz", "status": "running" }

Terminal shows the workflow completing after the response:

[Workflow Log] 👋 Hello from Vercel Workflow!

The API returned in ~100-200ms. The workflow finished a moment later. That's the pattern.

Solution

The key insight is fire-and-forget: calling start() schedules durable execution without blocking. Your route handler doesn't await the workflow — it kicks it off and moves on.

This is a deliberate tradeoff. Blocking until completion would tie up your function for the entire workflow duration — seconds, minutes, even hours for complex flows. Instead, start() returns a handle instantly, and the workflow engine takes over. You get sub-200ms API responses regardless of how long the actual work takes.

The consequence: your API can't return the workflow's result directly. You'll need to poll, use webhooks, or check execution status later. That's the deal — fast APIs in exchange for async result handling.

What's Happening

The API doesn't wait for the workflow to finish. It starts the workflow and returns immediately.

POST /api/workflow/{id}/execute
├── Create execution record
├── start(executeWorkflow, [...])  ← kicks off background work
└── Return { executionId, status: "running" }  ← instant

Background (continues after response):
├── Run each step
└── Update execution record when done

The start() function from @vercel/workflow schedules durable execution without blocking. The workflow runs with retries, step isolation, and logging built in.

// Don't await - just start it
executeWorkflowBackground(
  execution.id,
  workflowId,
  workflow.nodes,
  workflow.edges,
  input
);
 
// Return immediately
return NextResponse.json({
  executionId: execution.id,
  status: "running",
});

Commit

git add -A
git commit -m "chore: configure local dev environment for workflow builder"

Done

• Deploy button created your repo and provisioned Neon
• Cloned and running locally
• Ran a workflow
• API returned in under 200ms
• Saw "👋 Hello from Vercel Workflow!" in server logs
• Committed local setup

What's Next

You've seen workflows run in the background. But what if a workflow needs to wait for something external — a webhook, a user action, a payment confirmation? Lesson 2 shows how workflows pause and resume.