Configuration
The SDK is configured entirely by environment variables. There's no setup call — it reads them on first use, in every server runtime, for both producers and the route handler.
The two you need#
.env
NEXTMQ_CONNECTION_STRING=nextmq://v1....
NEXT_PUBLIC_APP_URL=https://your-app.com| Variable | Required | Description |
|---|---|---|
NEXTMQ_CONNECTION_STRING | Yes | One value from your dashboard. Bundles the server URL, your API key, and the webhook secret. Server-only — never expose it to the browser. |
NEXT_PUBLIC_APP_URL | Yes | Your app's public URL — where NextMQ calls back to run your jobs. |
Heads up
One key, one secret — and both are sensitive. The connection string bundles a single full-scope project key (enqueue, inspect, register workers, retry, remove, pause, obliterate) and a distinct webhook secret for signing callbacks. Keep it server-only — never put it in browser code or a
NEXT_PUBLIC_* variable.Manual mode#
Instead of a connection string you can set the three transport values directly — handy for local development against a throwaway project.
If NEXTMQ_CONNECTION_STRING is set, it wins over the manual transport variables.
NEXTMQ_SERVER_URL=http://localhost:3001
NEXTMQ_API_KEY=nextmq_dev_key
NEXTMQ_WEBHOOK_SECRET=dev_secret_1234567890
NEXT_PUBLIC_APP_URL=http://localhost:3000Optional#
| Variable | Default | Description |
|---|---|---|
NEXTMQ_WEBHOOK_BASE_URL | — | Override the callback origin when it differs from NEXT_PUBLIC_APP_URL (e.g. a tunnel in local dev, or pinning previews to one URL). |
NEXTMQ_REQUEST_TIMEOUT_MS | 15000 | Per-request timeout for SDK calls to NextMQ. Max 300000. |
NEXTMQ_WEBHOOK_BASE_PATH | /api/nextmq | Path your webhook route is mounted at. Must match where the route file lives. |
NEXTMQ_WEBHOOK_BODY_LIMIT_BYTES | 1048576 | Max accepted webhook payload size before the route responds 413. Max 10485760. |
How it resolves#
Configuration is read lazily on first use and cached per server runtime, so there's no module to import and no ordering to worry about — a producer in a server action and the webhook handler each pick it up from the environment independently.
Tip
Dynamic config? If you fetch secrets from a vault at boot, just set
process.env.NEXTMQ_CONNECTION_STRING before the first queue call (e.g. in Next.js instrumentation.ts). It's still env — there's no separate configure API.