AutoGineer
Generated banner for Upstash Qstash JS
Generated logo for Upstash Qstash JS

Upstash Qstash JS

UpstashOfficialCreated by Upstash

  • Skill
  • Tool integration
  • Automation and integrations
  • MIT
  • Low risk
  • Has scripts
Download ZIP

From the author

Work with the @upstash/qstash TypeScript/JavaScript SDK, an HTTP-based message queue, task scheduler, and background job system for serverless and edge runtimes (Next.js, Vercel, Cloudflare Workers, Deno, Node.js). Use when publishing messages to HTTP endpoints or URL groups, running background jobs without a long-running worker process, scheduling with cron expressions, delaying messages, building FIFO queues with parallelism and flow control, configuring retries and callbacks, handling a dead letter queue (DLQ), deduplicating messages, fanning out to multiple endpoints, verifying QStash webhook signatures (Next.js App Router, Pages Router, and Edge Runtime), running a local QStash dev server, or migrating regions. Also use when the user asks for a serverless cron job, async task queue, job scheduler, delayed delivery, webhook delivery with retries, or event-driven messaging between services.
— the description by Upstash

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The QStash JavaScript SDK provides a robust interface for interacting with Upstash's HTTP-based messaging and scheduling platform. Designed for serverless and edge environments like Next.js, Cloudflare Workers, and Deno, this skill enables developers to implement asynchronous task processing, cron-style scheduling, and reliable event-driven communication without maintaining persistent worker infrastructure.

What it does

  • Publishes HTTP messages to individual endpoints or URL groups
  • Schedules recurring tasks using cron expressions
  • Manages FIFO queues with configurable parallelism and flow control
  • Verifies incoming webhook signatures for secure communication
  • Handles advanced messaging patterns like retries, callbacks, and dead letter queues
  • Supports message deduplication and multi-region configurations

When to use it

  • When building serverless applications requiring background job processing
  • When you need to schedule delayed or recurring tasks in edge runtimes
  • When implementing event-driven architectures between microservices
  • When you need reliable webhook delivery with automatic retries
  • When you need to ensure ordered message processing with flow control

Advantages

  • Native support for serverless and edge runtimes
  • Simplifies complex background job orchestration
  • Built-in security via webhook signature verification
  • Flexible configuration for retries, delays, and dead letter queues
  • Supports local development workflows

Usage examples

“How do I publish a JSON message to a webhook using QStash?”
The agent provides a code snippet using the Client.publishJSON method, demonstrating how to initialize the client with an environment token and send a payload to a specific URL.
“How can I verify that a webhook request came from QStash?”
The agent explains how to use the Receiver class to validate incoming request signatures, including platform-specific guidance for frameworks like Next.js.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/upstash/upstash-qstash-js/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip upstash-qstash-js.zip -d .agents/skills

Documentation by Upstash

QStash JavaScript SDK

QStash is an HTTP-based messaging and scheduling solution for serverless and edge runtimes. This skill helps you use the QStash JS SDK effectively.

Bundled docs and source

Before writing or debugging SDK code, check node_modules/@upstash/qstash/docs/ for bundled docs and node_modules/@upstash/qstash/src/ for readable TypeScript source. Read and search the relevant files when present; otherwise use the references in this skill.

When to use this skill

Use this skill when:

  • Publishing HTTP messages to endpoints or URL groups

  • Creating scheduled or delayed message delivery

  • Managing FIFO queues with configurable parallelism

  • Verifying incoming webhook signatures from QStash

  • Implementing callbacks, DLQ handling, or message deduplication

Quick Start

Installing the SDK
npm install @upstash/qstash
Basic Publishing
import { Client } from "@upstash/qstash";

const client = new Client({
  token: process.env.QSTASH_TOKEN!,
});

const result = await client.publishJSON({
  url: "https://my-api.example.com/webhook",
  body: { event: "user.created", userId: "123" },
});

Core Concepts

For fundamental QStash operations, see:

For verifying incoming messages:

  • Receiver Verification - Core signature verification with the Receiver class

  • Platform-Specific Verifiers:

    • Next.js - App Router, Pages Router, and Edge Runtime

For advanced features:

Platform Support

QStash JS SDK works across various platforms:

  • Next.js (App Router and Pages Router)

  • Cloudflare Workers

  • Deno

  • Node.js (v18+)

  • Vercel Edge Runtime

  • SvelteKit, Nuxt, SolidJS, and other frameworks

Note on Workflow SDK: For building complex durable workflows that chain multiple QStash messages together, consider using the separate QStash Workflow SDK (@upstash/workflow). The Workflow SDK empowers you to orchestrate multi-step processes with automatic state management, retries, and fault tolerance. This Skills file focuses on the core QStash messaging SDK.

Best Practices

  • Always verify incoming QStash messages using the Receiver class

  • Use environment variables for tokens and signing keys

  • Set appropriate retry counts and timeouts for your use case

  • Use queues for ordered processing with controlled parallelism

  • Implement DLQ handling for failed message recovery

Files

advanced/multi-region/summary.md

Multi-Region Setup

Overview

QStash supports multi-region deployments across EU (EU_CENTRAL_1) and US (US_EAST_1) regions.

Requirements

Multi-region support requires minimum SDK versions:

  • @upstash/qstash >= 2.9.0

  • @upstash/workflow >= 1.1.0 (if using workflows)

Update your dependencies:

npm install @upstash/qstash@latest
# or if using workflows
npm install @upstash/qstash@latest @upstash/workflow@latest

When to Use Multi-Region

Consider multi-region QStash when:

  • You're migrating from one region to another

Understanding Multi-Region Mode

Multi-region mode is activated by setting the QSTASH_REGION environment variable to your primary region (EU_CENTRAL_1 or US_EAST_1). When active:

  • Outgoing messages use region-specific credentials

  • Incoming messages are verified using region-specific signing keys

  • The SDK automatically handles region detection

Environment Variable Setup

Single-Region Setup (Default)

For single-region deployments (EU only):

# Outgoing messages
QSTASH_TOKEN="your_token"

# Incoming message verification (optional)
QSTASH_CURRENT_SIGNING_KEY="your_current_key"
QSTASH_NEXT_SIGNING_KEY="your_next_key"

Optionally specify a custom URL:

QSTASH_URL="https://qstash.upstash.io"  # EU region (default)
QSTASH_TOKEN="your_token"
QSTASH_CURRENT_SIGNING_KEY="your_current_key"
QSTASH_NEXT_SIGNING_KEY="your_next_key"
Multi-Region Setup

For multi-region deployments with US as primary:

# Enable multi-region mode with US as primary
QSTASH_REGION="US_EAST_1"

# Outgoing messages - US region (primary)
US_EAST_1_QSTASH_URL="https://qstash-us-east-1.upstash.io"
US_EAST_1_QSTASH_TOKEN="your_us_token"

# Outgoing messages - EU region (only needed for Upstash Workflow)
EU_CENTRAL_1_QSTASH_URL="https://qstash.upstash.io"
EU_CENTRAL_1_QSTASH_TOKEN="your_eu_token"

# (Optional) Incoming message verification - US region
US_EAST_1_QSTASH_CURRENT_SIGNING_KEY="your_us_current_key"
US_EAST_1_QSTASH_NEXT_SIGNING_KEY="your_us_next_key"

# (Optional) Incoming message verification - EU region
EU_CENTRAL_1_QSTASH_CURRENT_SIGNING_KEY="your_eu_current_key"
EU_CENTRAL_1_QSTASH_NEXT_SIGNING_KEY="your_eu_next_key"

For multi-region with EU as primary, set QSTASH_REGION="EU_CENTRAL_1".

Getting Region-Specific Credentials

Sign in to the Upstash Console to find:

  • US Region: https://qstash-us-east-1.upstash.io

  • EU Region: https://qstash.upstash.io

Each region has its own:

  • API token for outgoing requests

  • Signing keys for incoming request verification

You can get all envrionment variables required for multi region setup using the Migrate button in the region list page.

How Outgoing Messages Work

Single-Region Mode

When QSTASH_REGION is not set:

  1. SDK reads QSTASH_URL and QSTASH_TOKEN

  2. If QSTASH_URL is not set, defaults to EU region

  3. All messages are published through this region

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

// Uses QSTASH_TOKEN and QSTASH_URL (or EU default)
const client = new Client({
  token: process.env.QSTASH_TOKEN!,
});

await client.publishJSON({
  url: "https://my-api.com/webhook",
  body: { message: "hello" },
});
Multi-Region Mode

When QSTASH_REGION is set to a valid region:

  1. SDK reads region-specific credentials (e.g., US_EAST_1_QSTASH_URL)

  2. All messages are published through the specified primary region

  3. If region-specific credentials are missing, falls back to default credentials with a warning

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

// Automatically uses US_EAST_1_QSTASH_TOKEN and US_EAST_1_QSTASH_URL
// based on QSTASH_REGION="US_EAST_1"
const client = new Client();

await client.publishJSON({
  url: "https://my-api.com/webhook",
  body: { message: "hello" },
});
Credential Resolution Priority

The SDK resolves credentials in this order:

  1. Config overrides: Explicitly passed token and baseUrl

  2. Region-specific: Based on QSTASH_REGION (e.g., US_EAST_1_QSTASH_TOKEN)

  3. Default credentials: QSTASH_TOKEN and QSTASH_URL

  4. Default URL: https://qstash.upstash.io (EU) with token from environment

// Override with explicit credentials
const client = new Client({
  token: "custom_token",
  baseUrl: "https://qstash-us-east-1.upstash.io",
});

How Incoming Messages Work

Understanding the Region Header

QStash includes an upstash-region header with every request indicating the source region:

upstash-region: US-EAST-1

The SDK uses this header to determine which signing keys to use for verification.

Single-Region Verification

In single-region mode, the SDK uses default signing keys:

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

const receiver = new Receiver({
  currentSigningKey: process.env.QSTASH_CURRENT_SIGNING_KEY!,
  nextSigningKey: process.env.QSTASH_NEXT_SIGNING_KEY!,
});

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

In multi-region mode, the SDK:

  1. Checks the upstash-region header from the request

  2. Normalizes it (converts US-EAST-1 → US_EAST_1)

  3. Looks for region-specific signing keys (e.g., US_EAST_1_QSTASH_CURRENT_SIGNING_KEY)

  4. Falls back to default keys if region-specific keys are missing

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

// Auto-detects region from QSTASH_REGION environment
const receiver = new Receiver();

await receiver.verify({
  signature: request.headers.get("upstash-signature")!,
  body: await request.text(),
  upstashRegion: request.headers.get("upstash-region") ?? undefined,
});
Signing Key Resolution Priority

The SDK resolves signing keys in this order:

  1. Config overrides: Explicitly passed signing keys

  2. Region-specific: Based on upstash-region header (e.g., US_EAST_1_QSTASH_CURRENT_SIGNING_KEY)

  3. Default keys: QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY

Platform-Specific Verification

On most platforms, verifiers automatically handle multi-region verification.

// Next.js App Router
import { verifySignatureAppRouter } from "@upstash/qstash/nextjs";

export const POST = verifySignatureAppRouter(async (req) => {
  // Automatically handles multi-region verification
  const body = await req.json();
  return Response.json({ success: true });
});

In cloudflare workers, it's not possible right now but it will be supported in the future.

Migration from Single to Multi-Region

Step-by-Step Migration
Step 1: Add Multi-Region Credentials

Keep your existing credentials and add region-specific ones:

# Existing (keep these)
QSTASH_TOKEN="your_eu_token"
QSTASH_CURRENT_SIGNING_KEY="your_eu_current_key"
QSTASH_NEXT_SIGNING_KEY="your_eu_next_key"

# New multi-region credentials
QSTASH_REGION="US_EAST_1"  # Set your primary region

US_EAST_1_QSTASH_URL="https://qstash-us-east-1.upstash.io"
US_EAST_1_QSTASH_TOKEN="your_us_token"
US_EAST_1_QSTASH_CURRENT_SIGNING_KEY="your_us_current_key"
US_EAST_1_QSTASH_NEXT_SIGNING_KEY="your_us_next_key"

EU_CENTRAL_1_QSTASH_URL="https://qstash.upstash.io"
EU_CENTRAL_1_QSTASH_TOKEN="your_eu_token"  # Can reuse existing
EU_CENTRAL_1_QSTASH_CURRENT_SIGNING_KEY="your_eu_current_key"
EU_CENTRAL_1_QSTASH_NEXT_SIGNING_KEY="your_eu_next_key"
Step 2: Update Verification Code

Add region header to verification calls:

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

// After (multi-region ready)
await receiver.verify({
  signature: request.headers.get("upstash-signature")!,
  body: await request.text(),
  upstashRegion: request.headers.get("upstash-region") ?? undefined,
});
Step 3: Verify Setup

Use the verification script to confirm your env variable setup:

npx tsx advanced/multi-region/verify-multi-region-setup.ts

Troubleshooting

Common Issues
"No signing keys available for verification"

Cause: Neither default nor region-specific signing keys are found.

Solution: Verify environment variables are set:

# Single-region
echo $QSTASH_CURRENT_SIGNING_KEY
echo $QSTASH_NEXT_SIGNING_KEY

# Multi-region
echo $QSTASH_REGION
echo $US_EAST_1_QSTASH_CURRENT_SIGNING_KEY
echo $US_EAST_1_QSTASH_NEXT_SIGNING_KEY

Best Practices

Always Pass Region Header

When verifying in multi-region mode, always pass the upstash-region header:

// ✅ Good - region-aware verification
await receiver.verify({
  signature: request.headers.get("upstash-signature")!,
  body: await request.text(),
  upstashRegion: request.headers.get("upstash-region") ?? undefined,
});

// ⚠️ Works but may use wrong keys in multi-region
await receiver.verify({
  signature: request.headers.get("upstash-signature")!,
  body: await request.text(),
  // Missing upstashRegion - will use default keys
});
Test Both Regions

When setting up multi-region, test messages from both regions:

# Trigger messages from US region
curl -X POST https://qstash-us-east-1.upstash.io/v2/publish/... \
  -H "Authorization: Bearer $US_EAST_1_QSTASH_TOKEN"

# Trigger messages from EU region
curl -X POST https://qstash.upstash.io/v2/publish/... \
  -H "Authorization: Bearer $EU_CENTRAL_1_QSTASH_TOKEN"
Gradual Migration

Migrate gradually to minimize risk:

  1. Add multi-region credentials alongside existing ones

  2. Update verification code to handle region header

  3. Test in staging environment

  4. Activate multi-region mode in production

  5. Monitor for warnings and errors

Verification Script

Use the provided script to verify your environment setup:

# Option 1: Using bun (automatically loads .env)
bun run advanced/multi-region/verify-multi-region-setup.ts

# Option 2: Using tsx with dotenv
npm install dotenv
npx tsx -r dotenv/config advanced/multi-region/verify-multi-region-setup.ts

The script checks:

  • Whether setup is single-region or multi-region

  • Which region will be used for outgoing messages

  • Whether all required environment variables are present

  • If there are any configuration issues

See verify-multi-region-setup.ts for implementation details.

Related Documentation

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

What our scanner noticed· Low risk

  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Upstash
Publisher
Upstash (Official)
Source
upstash/skills · skills/upstash-qstash-js · commit 9f9e3e5
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Upstash or Upstash.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download upstash-qstash-js.zip