Deploying to Vercel

There's no infrastructure to deploy — NextMQ runs the queue. You just deploy your Next.js app with the right environment.

Set your environment#

Add the connection string and your app URL in Project → Settings → Environment Variables. Use the same connection string across all environments(Production, Preview, and Development) — that's what makes preview routing work.

NEXTMQ_CONNECTION_STRING=nextmq://v1....
NEXT_PUBLIC_APP_URL=https://your-app.com

See Configuration for what each value does.

Preview deployments just work#

Each Vercel deployment gets a unique URL. NextMQ handles that for you: your production deployment registers the queue's canonical consumer, and every deployment stamps its own URL on the jobs it enqueues. The server delivers each job back to the deployment that created it — so a preview's jobs run on that preview, signed with the shared webhook secret from your connection string.

Production deploy
  registers canonical worker URL -> https://your-app.com/api/nextmq/worker/emails

Preview deploy
  enqueues a job with callbackUrl -> https://branch-git-feature.vercel.app/api/nextmq/worker/emails

Scheduler jobs
  use the canonical worker URL because they are not created by a preview request

Heads up

Deployment Protection.Preview URLs are often gated by Vercel Authentication, which will reject NextMQ's webhook with a 401. Enable Protection Bypass for Automation (or disable protection for previews) so deliveries reach them.

Pinning a callback origin (optional)#

To send every callback to one fixed origin instead of per-deployment routing, set NEXTMQ_WEBHOOK_BASE_URL. When set, it overrides the per-deployment URL and all jobs call back there.

NEXTMQ_WEBHOOK_BASE_URL=https://your-app.com

Register workers on deploy#

A worker publishes its webhook URL to NextMQ once, and that registration is durable — it doesn't lapse while a queue sits idle, so there's nothing to keep alive. Do it at boot with startup registration (recommended), or hit /api/nextmq/health once after your first deploy.

Local development#

NextMQ calls your app over the public internet, so localhost needs a tunnel. See Local development for ngrok and Cloudflare Tunnel setup.

Separate dev and prod#

Want isolated queues, keys, and metrics per environment? Create a separate project — each gets its own connection string — and set the dev one for Preview + Development and the prod one for Production. Isolation is per-project, so dev can never touch prod data.

Note

Not on Vercel? Any platform works the same way — expose the Node.js route at a public HTTPS URL, keep NEXTMQ_CONNECTION_STRING server-only, and set NEXTMQ_WEBHOOK_BASE_URL if your callback origin differs from NEXT_PUBLIC_APP_URL.

Before you ship#

The same NEXTMQ_CONNECTION_STRING set across all environments.
NEXT_PUBLIC_APP_URL points at your deployed domain.
Preview Deployment Protection bypassed for automation, if you use previews.
Processors are idempotent — see Reliability & delivery guarantees.
Workers register on deploy — via startup registration or a one-time /api/nextmq/health hit.

PreviousRegistering on startup NextReliability & delivery