qstash-js

@upstash/qstash is the official TypeScript client for QStash, Upstash’s HTTP-based message queue built for serverless and edge runtimes (Lambda, Cloudflare Workers, Vercel Edge, Deno). Instead of holding a persistent TCP connection to a broker, applications publish messages over plain HTTP with a bearer token, and QStash durably stores and retries delivery to a destination URL — making it usable from any request/response environment, including the browser.

The package wraps the full QStash API surface: publishing and batch publishing, FIFO queues with flow control, cron-based and one-off schedules, dead-letter queues, URL groups (fan-out), and content-based or explicit-id deduplication. A separate Receiver class verifies inbound webhook signatures independently of the publishing client. On top of that transport layer sits a Workflow module that turns a single serverless handler into a resumable, multi-step durable function, plus dedicated adapters for Next.js, Nuxt, SvelteKit, SolidStart, Hono, H3, and Cloudflare Workers.

What You Get

• A Client for publishing JSON or raw messages to a URL, a named URL group, or a queue, with configurable retry/backoff
• A Receiver class that independently verifies the Upstash-Signature header on inbound webhook deliveries
• Schedules, Queue, UrlGroups, and DLQ classes covering cron/delayed delivery, FIFO queues with flow control, fan-out groups, and dead-letter inspection
• A Workflow module (serve, step primitives, context) for writing resumable multi-step serverless functions backed by QStash
• Ready-made platform adapters for Next.js, Nuxt, SvelteKit, SolidStart, Hono, H3, and Cloudflare Workers
• A local dev server (QSTASH_DEV=true) that auto-downloads and manages a QStash emulator with deterministic credentials for offline development

Common Use Cases

• Fanning out background jobs from serverless functions without running a worker process
• Delivering webhooks reliably with built-in retries, backoff, and deduplication
• Building resumable multi-step workflows that survive timeouts and cold starts
• Scheduling recurring or delayed HTTP calls (cron-style) from an edge or serverless app
• Verifying that an inbound request genuinely originated from QStash before processing it

Under The Hood

Architecture A single HttpClient (src/client/http.ts) is the shared fetch-based transport — handling retry/backoff, telemetry headers, and local dev-server redirection — that every domain class composes over rather than reimplementing. Client (src/client/client.ts) instantiates one HttpClient and wires thin domain classes (DLQ, FlowControlApi, Chat, Messages, Queue, Schedules, UrlGroups, Workflow) around it via constructor composition, a facade-over-shared-transport pattern with no DI framework involved. Receiver is a parallel, independent verification path built on jose JWT primitives, decoupled from Client since signature checking runs on the receiving server rather than the publisher. The workflow/ subsystem (auto-executor, context, steps, serve, workflow-requests) is the densest part of the codebase, implementing a step-serialization/resume protocol so one HTTP handler can represent a multi-step durable function.

Tech Stack Pure TypeScript built with tsup for dual ESM/CJS output, exposing a dedicated entry point per framework (index, nextjs, h3, nuxt, svelte, solidjs, workflow, hono, cloudflare) as declared in the package’s exports map. Runtime dependencies are deliberately minimal: jose for JWT-based signature verification, crypto-js for hashing, and neverthrow for Result-based error handling in select code paths. Bun is the required dev/test runtime, with framework packages (next, hono, h3, @sveltejs/kit, @solidjs/start) present only as devDependencies for type-checking their respective adapters. Husky and commitlint enforce conventional commits, and GitHub Actions gates every PR through a shared test workflow and publishes on release.

Code Quality Thirty *.test.ts files sit alongside their implementations and run via bun test, including integration-style suites for multi-region and workflow behavior. ESLint extends @typescript-eslint/strict-type-checked and stylistic-type-checked plus eslint-plugin-unicorn’s recommended rules — a notably strict lint posture — and tsconfig.json runs in full strict mode. Errors are modeled as typed custom classes (QstashError, QstashRatelimitError, QstashChatRatelimitError, QstashDailyRatelimitError, QstashEmptyArrayError) rather than generic throws, naming is consistent and descriptive throughout, and inline documentation comments are extensive across the public API surface.

What Makes It Unique Beyond acting as a thin REST wrapper, the package bundles a full durable-workflow engine (serve() plus step primitives) that round-trips execution state through QStash itself, an auto-provisioning local dev server that downloads and runs a QStash emulator with deterministic keys, and a built-in LLM-publish path that lets a single publishJSON call schedule and proxy chat-completion requests through a provider with optional analytics wired in. Durable workflows-as-a-library and automatic dev-server provisioning go well beyond what typical queue SDKs offer.