Upstash Qstash JS

Local Development

Use the QStash dev server to test publishing and signature verification end-to-end on your machine — no public tunnel, no real QStash account, no real signing keys.

Automatic dev server (recommended)

Pass devMode: true to the Client (and the matching verifier). The SDK will download the QStash CLI binary, start it, and wire credentials for you.

import { Client } from "@upstash/qstash";

const client = new Client({ devMode: true });

await client.publishJSON({
  url: "https://example.com/webhook",
  body: { hello: "world" },
});

When devMode is on:

• The SDK downloads the latest qstash binary on first use, caches it under the OS cache directory, and reuses it across projects.

• Spawns the dev server on port 8080 (override via QSTASH_DEV_PORT).

• Reuses an already-running server on the configured port instead of spawning a duplicate.

• Injects deterministic dev baseUrl, token, and signing keys. Any explicit token / baseUrl / signing keys you pass are ignored (a warning is printed). To use real credentials, set devMode: false.

• Forwards dev server logs to stdout/stderr with a dim [QStash CLI] prefix.

• No-ops in production (NODE_ENV=production), during next build, and in browser/edge runtimes.

Environment variable

Instead of hard-coding devMode: true, leave the option unset and toggle via env:

QSTASH_DEV=true       # or "1"
QSTASH_DEV_PORT=8080  # optional, default 8080

The resolution order is: explicit devMode boolean > QSTASH_DEV env var > off. Use this so production code never accidentally turns the dev server on.

Verifying signatures in dev

The receiving side also needs devMode: true so it verifies against the dev server's deterministic signing keys instead of your real ones.

import { Receiver } from "@upstash/qstash";

const receiver = new Receiver({ devMode: true });

await receiver.verify({
  signature: request.headers.get("upstash-signature")!,
  body: await request.text(),
});

For Next.js, the wrappers accept the same flag:

// app/api/webhook/route.ts
import { verifySignatureAppRouter } from "@upstash/qstash/nextjs";

export const POST = verifySignatureAppRouter(
  async (request) => new Response("ok"),
  { devMode: true }
);

Next.js: starting the server before edge routes

Edge runtimes cannot spawn child processes. If a route in the Edge Runtime is the first thing to use QStash, the SDK can only check whether the server is reachable — it cannot start it. Call registerQStashDev() from instrumentation.ts to spawn the server during Next.js startup, before any request hits:

// instrumentation.ts
import { registerQStashDev } from "@upstash/qstash/nextjs";

export function register() {
  registerQStashDev();
}

registerQStashDev is itself a no-op in production and during next build.

Common pitfalls

• Passing token alongside devMode: true — the explicit token is ignored and you get a console warning. Drop the token field, or set devMode: false to use it.

• Hitting build-time errors in next build — if a route module is evaluated at build time and instantiates the Client, mark the route export const dynamic = "force-dynamic" so it isn't pre-rendered.

• Port 8080 already in use — the SDK errors with a clear message; either stop the other process or set QSTASH_DEV_PORT to a free port (matched on both client and receiver sides).

• Calling QStash from an edge route without instrumentation.ts — the edge runtime can't spawn the binary. Either move the call to a Node-runtime route or wire registerQStashDev() as shown above.

Manual dev server

If you cannot use the automatic flow (non-Node runtime, CI without internet, custom binary), run the CLI yourself:

npx @upstash/qstash-cli dev

Then construct the client with the printed dev credentials explicitly and leave devMode unset/false:

const client = new Client({
  baseUrl: "http://127.0.0.1:8080",
  token: "eyJVc2VySUQiOiJkZWZhdWx0VXNlciIsIlBhc3N3b3JkIjoiZGVmYXVsdFBhc3N3b3JkIn0=",
});

See the Local Development docs for the full list of test users and CLI options.