qstash-js

QStash JavaScript SDK

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

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

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

• エンドポイントまたは 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 グループ

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

• 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 処理を実装してください。