GitHub Repository
You can find the project source code on GitHub.
Prerequisites
- Node.js and pnpm installed.
Step 1: Create a new TanStack Start project
Run the following command to create a new TanStack Start project:Step 2: Installation
Run the following command to install the Upstash Workflow SDK in your TanStack Start app.- pnpm
- npm
- bun
Step 3: Run the development server
Upstash Workflow is built on top of Upstash QStash. In a production environment, your application connects to the managed QStash servers hosted by Upstash. This ensures that requests are delivered reliably, securely, and at scale without requiring you to run and maintain your own infrastructure. For local development, you don’t need to depend on the managed QStash servers. Instead, you can run a local QStash server directly on your machine. This local server behaves just like the production version but does not require external network calls. Start the local server with:- pnpm
- npm

Step 4: Configure Environment Variables
Next, you need to configure your TanStack Start app to connect with the local QStash server by setting environment variables. In the root of your project, create a.env
file (or update your existing one) and add the values printed by the QStash local server:
For production, replace these with your actual credentials from the Upstash Workflow dashboard.
Step 5: Create a Workflow Endpoint
With your environment ready, the next step is to define your first workflow endpoint. In Upstash Workflow, every workflow is exposed as an endpoint. Every endpoint you expose using the SDK’sserve()
function acts as a workflow that can be triggered independently.
In TanStack Start, these endpoints are implemented as API routes using the file-based routing system.
Create a new file src/routes/api/workflow.ts
:
src/routes/api/workflow.ts
Step 6: Start your TanStack Start app
Start your TanStack Start development server:- pnpm
- npm
http://localhost:3000
.
Step 7: Run the Workflow Endpoint
Once your endpoint is defined, the next step is to trigger a workflow run. You can start a new workflow run using thetrigger()
function from the Upstash Workflow SDK.
The
trigger()
function should typically be called from a server-side action (not directly in client-side code) to keep your credentials secure.
Inside the
trigger()
call, you need to provide the URL of your workflow endpoint:- Local development → use the URL where your app is running, for example: http://localhost:3000/api/workflow
- Production → use the URL of your deployed app, for example: https://yourapp.com/api/workflow
BASE_URL
constant and set it based on the environment:Next Steps
Now that you’ve created your first workflow, here are some recommended guides to continue learning:- Learn the Workflow API: Dive deeper into the full API surface and advanced capabilities.
- Configure Workflow Runs: Learn how to configure workflow execution to fit your app’s needs.
- Handle Failures: Understand how to detect and recover from failed workflow runs.