upstash-qstash-js

QStash JavaScript SDK

QStash は、サーバーレス環境やエッジランタイム向けの HTTP ベースのメッセージングおよびスケジューリングソリューションです。このスキルでは、QStash JS SDK を効果的に利用する方法を説明します。

同梱ドキュメントとソースコード

SDK コードの作成やデバッグを行う前に、同梱ドキュメントがある場合は node_modules/@upstash/qstash/docs/ を、読みやすい TypeScript ソースコードがある場合は node_modules/@upstash/qstash/src/ を確認してください。関連ファイルがあれば、読み込んで検索してください。ない場合は、このスキルに記載されたリファレンスを使用してください。

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

• エンドポイントまたは URL グループへの HTTP メッセージのパブリッシュ
• スケジュール配信または遅延配信の作成
• 並列処理数を設定できる FIFO キューの管理
• QStash からの受信 Webhook 署名の検証
• コールバック、DLQ 処理、またはメッセージの重複排除の実装

クイックスタート

SDK のインストール

npm install @upstash/qstash

基本的なパブリッシュ

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" },
});

主な概念

QStash の基本的な操作については、次を参照してください。

• メッセージのパブリッシュ
• スケジュール
• キューとフロー制御
• URL グループ
• ローカル開発 — devMode: true による開発サーバーの自動起動

受信メッセージの検証については、次を参照してください。

• Receiver による検証 - Receiver クラスを使った基本的な署名検証
• プラットフォーム固有の検証機能：
  • Next.js - App Router、Pages Router、Edge Runtime

高度な機能については、次を参照してください。

• コールバック
• デッドレターキュー（DLQ）
• メッセージの重複排除
• リージョンの移行とマルチリージョンサポート
  • 必要に応じて、マルチリージョンの環境変数設定検証スクリプトを使用してください。引数なしで実行できます。

プラットフォームのサポート

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 を使うと、自動状態管理、リトライ、フォールトトレランスを備えた複数ステップのプロセスをオーケストレーションできます。この Skills ファイルでは、コアとなる QStash メッセージング SDK に焦点を当てています。

ベストプラクティス

• Receiver クラスを使用して、QStash からの受信メッセージを必ず検証してください。
• トークンと署名キーには環境変数を使用してください。
• ユースケースに適したリトライ回数とタイムアウトを設定してください。
• 並列処理数を制御しながら順序どおりに処理するには、キューを使用してください。
• 失敗したメッセージを復旧できるよう、DLQ 処理を実装してください。