Registering on startup

By default you register workers by calling ensureWorkersRegistered (e.g. by hitting the handler's /health path), and create schedulers by hand. Move both into your app's startup so a fresh deploy is wired up the moment it boots.

The register() hook#

Next.js calls the register export in instrumentation.ts once when the server starts. It is the place to register your workers and create your schedulers — no route has to be hit and no script has to be run.

instrumentation.ts

export async function register() {
  // Server-only: skip the Edge runtime.
  if (process.env.NEXT_RUNTIME !== 'nodejs') return

  const { ensureWorkersRegistered } = await import('@nextmq/sdk/next')
  const { Queue } = await import('@nextmq/sdk')
  const { summarizeWorker } = await import('@/jobs/ai')

  try {
    // Publish each worker's webhook URL up front.
    await ensureWorkersRegistered([summarizeWorker])

    // Create repeatable schedulers so a fresh deploy already has them.
    await new Queue('reports').upsertJobScheduler('daily-report', {
      pattern: '0 9 * * *',
    })
  } catch (err) {
    // Best-effort: never crash boot. You can still register by hitting /api/nextmq/health.
    console.error('[nextmq] startup registration failed', err)
  }
}

Note

Use dynamic import() inside register and guard on NEXT_RUNTIME === 'nodejs' so server-only SDK code never loads in the Edge runtime. Both calls are idempotent, so they are safe to run on every boot.

Why startup, not a route call#

Until something calls ensureWorkersRegistered — at boot, or by hitting /api/nextmq/health— a fresh deploy has no registered worker, and a scheduler only exists once you upsert it. Registering on boot means producers can enqueue and schedulers tick the moment you deploy, with no "remember to ping the route" step. Registration is durable, so you do it once per deploy, not on a timer.

What runs when#

Environment	register() fires
Long-running Node server	Once, at process boot.
Serverless (Vercel)	On each cold start — i.e. the first request that boots an instance, not at deploy time. Idempotent, so safe to repeat.

Note

Registration uses the same NEXTMQ_CONNECTION_STRING and NEXT_PUBLIC_APP_URL as the rest of the SDK — see Configuration. On Next.js 15+, instrumentation.ts is stable with no flag; older versions need experimental.instrumentationHook in next.config.

PreviousLocal development NextDeploying to Vercel