Vercel + DBOS Integration

The Vercel + DBOS Integration is a reference template for running durable background workflows on Vercel using the DBOS TypeScript framework, combining a Next.js frontend with serverless Vercel Functions. It demonstrates how to offload long-running or scheduled work from request/response code into a reliable background worker, using Postgres as the underlying workflow store via Supabase.

What is the Vercel + DBOS Integration?

The Vercel + DBOS Integration is an open-source reference app that shows how to run durable background tasks on Vercel. It pairs a Next.js frontend with a serverless Vercel Functions backend: the frontend uses a DBOS Client backed by Postgres to enqueue workflows and display their status, while a worker running in a Vercel Function picks up and executes those enqueued workflows. The template is maintained by DBOS and is designed to be deployed in one click with a Supabase integration.

Key Features

• Durable background workflows — Workflows survive individual function restarts and are tracked in Postgres, so long-running tasks can be resumed instead of restarted.
• Next.js frontend with DBOS Client — The app's UI enqueues new workflows and polls workflow status through the DBOS TypeScript client.
• Serverless worker in Vercel Functions — A worker function polls for and executes enqueued workflows, keeping the CPU-heavy work out of the web request path.
• Automatic trigger via Vercel cron — A built-in Vercel cron schedule invokes the worker, with a default of once a day to respect free-tier limits; on paid plans you can set it as often as every minute.
• Manual trigger button — The app includes a button that invokes the worker on demand, useful for testing or when you want immediate execution.
• One-click deployment with Supabase — The template ships with a Vercel Deploy button that clones the repository and provisions the Supabase Postgres storage integration automatically.

Who is it for?

• Next.js developers on Vercel who must run scheduled or background jobs and want a reference implementation that uses only Vercel-native serverless functions plus Postgres.
• Developers new to durable execution who need a minimal, deployable example of DBOS's workflow engine integrated with a popular framework.
• Teams using Supabase that want a template where the database layer is already wired into the deployment flow.

What can you do with it?

• Deploy a durable job worker in minutes: Use the one-click Vercel deploy link to get a working Next.js + DBOS + Supabase stack, then adapt the worker function to your own background logic.
• Learn how to enqueue workflows from a web app: The frontend demonstrates the DBOS client pattern for posting workflow requests and polling status through the UI.
• Extend the cron worker: Change the Vercel cron schedule to fit your workload — daily for free-tier cost limits, up to once a minute on paid plans — and add your own processing inside the worker function.

How does it work?

The user (or an API endpoint) uses the DBOS Client in the Next.js frontend to enqueue a workflow, which is persisted in Postgres. A worker running as a Vercel Function periodically polls the database for pending workflows and executes them, updating their status so the frontend can display results. The worker can be triggered by a Vercel cron job or manually through a button in the app.

FAQ

Is the Vercel + DBOS Integration free?

The template itself is open source and freely available, and you can deploy the reference app on Vercel's free tier. The built-in cron schedule is intentionally set to once a day on free plans; Vercel limits cron frequency for free deployments, so you can raise the frequency if you're on a paid Vercel plan.

What database does it use?

Workflow state is stored in Postgres, provided by Supabase through an integration that is configured automatically when you deploy with the provided Vercel button. The DBOS Client uses this Postgres connection to persist enqueued workflows and results.

Can I run background jobs without a separate server?

Yes. The worker runs inside a Vercel Function, so you do not need a dedicated VM or container. The DBOS pattern stores the execution state in Postgres, which lets a stateless serverless function resume or continue a durable workflow across invocations.

How often can the worker run?

The template's default cron schedule is once a day because of Vercel's free-tier limits. On a non-free plan you can configure the cron to run as often as you want — the DBOS documentation recommends once a minute for typical background job polling.