Back to Details

qstash-js

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

QStash JavaScript SDK

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.
QStash是一款面向无服务器及边缘运行时的基于HTTP的消息传递与调度解决方案。本指南将帮助你高效使用QStash JS SDK。

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
在以下场景中使用本技能：
  • 向端点或URL组发布HTTP消息
  • 创建定时或延迟消息投递任务
  • 管理可配置并行度的FIFO队列
  • 验证来自QStash的传入Webhook签名
  • 实现回调、死信队列（DLQ）处理或消息去重

Quick Start

快速开始

Installing the SDK

安装SDK

bash
npm install @upstash/qstash
bash
npm install @upstash/qstash

Basic Publishing

基础消息发布

typescript
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" },
});
typescript
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:
  • Publishing Messages
  • Schedules
  • Queues and Flow Control
  • URL Groups
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:
  • Callbacks
  • Dead Letter Queue (DLQ)
  • Message Deduplication
  • Region migration & multi-region support
    • If needed, multi-region env variable setup verification script. Can be run without arguments
关于QStash的基础操作，请查看：
  • 消息发布
  • 调度任务
  • 队列与流控
  • URL组
关于传入消息验证：
  • 接收方验证 - 使用Receiver类进行核心签名验证
  • 平台专属验证器：
    • Next.js - 支持App Router、Pages Router及Edge Runtime
关于高级功能：
  • 回调
  • 死信队列（DLQ）
  • 消息去重
  • 区域迁移与多区域支持
    • 如有需要，可使用多区域环境变量配置验证脚本，无需参数即可运行

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.
QStash JS SDK支持多种平台：
  • Next.js（App Router与Pages Router）
  • Cloudflare Workers
  • Deno
  • Node.js（v18+）
  • Vercel Edge Runtime
  • SvelteKit、Nuxt、SolidJS及其他框架
Workflow SDK说明：若要构建将多个QStash消息链接在一起的复杂持久化工作流，可考虑使用独立的QStash Workflow SDK（
@upstash/workflow
）。Workflow SDK支持你编排多步骤流程，具备自动状态管理、重试及容错能力。本技能文档聚焦于核心QStash消息传递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
  • 始终使用Receiver类验证传入的QStash消息
  • 使用环境变量存储令牌与签名密钥
  • 根据业务场景设置合适的重试次数与超时时间
  • 使用队列实现有序处理并控制并行度
  • 实现DLQ处理以恢复失败消息