upstash-workflow

Create a workflow class with static trigger methods using the Upstash Client, then define route handlers with serve() from @upstash/workflow/nextjs. Follow the three-layer pattern: a process entry point, a paginate layer with fan-out, and an execute layer handling one item per invocation.

Use the fan-out pattern in the pagination layer: split item lists exceeding CHUNK_SIZE (default 20) into chunks and recursively re-trigger the paginate workflow for each chunk. This avoids hitting workflow step limits on large pages.

flowControl configures concurrency per workflow endpoint using a key, parallelism, and ratePerSecond. Entry points typically use parallelism 1 to prevent duplicate batch triggers, while execution layers use parallelism 5-10 based on downstream API rate limits.

Upstash deduplicates context.run() calls by step name, so reusing the same step name in a loop drops results. Use unique step names like `workflow:execute:${item.id}` for each item processed in parallel.

Implement a dryRun mode in the entry point that returns statistics (totalEligible, toProcess, alreadyProcessed) without triggering side effects. Write integration tests covering both the dry-run path and the full execution path, then smoke-test with a small batch.

All workflows require APP_URL as the base URL for workflow endpoints and QSTASH_TOKEN for QStash authentication. QSTASH_URL is optional and only needed when using a custom QStash endpoint.