Hono
GitHub Repository
You can find the project source code on GitHub.
This guide provides detailed, step-by-step instructions on how to use and deploy Upstash Workflow with Hono. You can also explore our Hono example for a detailed, end-to-end example and best practices.
Prerequisites
- An Upstash QStash API key.
- Node.js and npm (another package manager) installed.
If you haven’t obtained your QStash API key yet, you can do so by signing up for an Upstash account and navigating to your QStash dashboard.
Step 1: Installation
First, install the QStash SDK in your Hono project:
npm install @upstash/qstash
Step 2: Configure Environment Variables
Create a .dev.vars
file in your project root and add your QStash token. This key is used to authenticate your application with the QStash service.
touch .dev.vars
Open the environment file and add your QStash token, as well as the environment you’re running in:
QSTASH_TOKEN=xxxxxxxxx
ENVIRONMENT=development
Replace xxxxxxxxx
with your actual QStash token found here:
Step 3: Create a Workflow Endpoint
A workflow endpoint allows you to define a set of steps that, together, make up a workflow. Each step contains a piece of business logic that is automatically retried on failure, with easy monitoring via our visual workflow dashboard.
To define a workflow endpoint with Hono, navigate into your entrypoint file (usually src/index.ts
) and add the following code:
import { Hono } from "hono"
import { serve } from "@upstash/qstash/hono"
const app = new Hono()
app.post("/workflow",
serve(async (context) => {
await context.run("initial-step", () => {
console.log("initial step ran")
})
await context.run("second-step", () => {
console.log("second step ran")
})
})
)
export default app
Step 4: Run the Workflow Endpoint
To start your Hono app locally, run the following command:
npm run dev
Executing this command prints a local URL to your workflow endpoint. By default, this URL is http://localhost:8787
.
You can verify your correct environment variable setup by checking the wrangler output, which should now have access to your QSTASH_TOKEN
binding and log your local URL:
For QStash, a tool that’s used to run a workflow under the hood, we need to provide a publically accessible URL. You can easily forward your localhost URL to a live URL by following our guide about setting up your workflow endpoint for local development.
Once you have a live URL, proceeed with either one of the following steps:
Setting an enviroment variable (recommended)
Set your publically accessible URL (without extensions such as /workflow
) as an environment variable. This variable is only needed for local development and doesn’t need to be set in production:
UPSTASH_WORKFLOW_URL=https://<YOUR_NGROK_OR_TUNNEL_URL>/
Using the baseUrl
option
As an alternative to setting an environment variable, you can also use the baseUrl
option in the serve
method. This option is only needed for local development and can be omitted in production:
import { Hono } from "hono"
import { serve } from "@upstash/qstash/hono"
const app = new Hono()
app.post("/workflow",
serve(async (context) => { ... }, {
// just the base URL, no `/workflow`
baseUrl: 'https://<YOUR_NGROK_OR_TUNNEL_URL>/'
})
)
export default app
Triggering the workflow
After setting your live URL as the environment variable or baseUrl
option, trigger your workflow by sending a POST request. For each workflow run, a unique workflow run ID is returned:
curl -X POST https://<YOUR_NGROK_OR_TUNNEL_URL>/workflow'
# result: {"workflowRunId":"wfr_xxxxxx"}
Use this ID to track the workflow run and see its status in your QStash workflow dashboard. All steps are listed with their statuses, headers, and body for a detailed overview of your workflow from start to finish. Click on a step to see its detailed logs.
Step 5: Deploying to Production
When deploying your Hono app with Upstash Workflow to production, there are a few key points to keep in mind:
-
Environment Variables: Make sure that all necessary environment variables from your
.dev.vars
file are set in your Cloudflare Worker project settings. For example, yourQSTASH_TOKEN
, and any other configuration variables your workflow might need. -
Remove Local Development Settings: In your production code, you can remove or conditionally exclude any local development settings. For example, the
baseUrl
option in theserve
function can be omitted in production.
import { Hono } from "hono"
import { serve, WorkflowBindings } from "@upstash/qstash/hono"
import { env } from "hono/adapter"
interface Bindings extends WorkflowBindings {
ENVIRONMENT: "development" | "production"
}
const app = new Hono<{ Bindings: Bindings }>()
app.post("/workflow", (c) => {
const { ENVIRONMENT } = env(c)
const handler = serve<unknown, Bindings>(
async (context) => { ... },
{
// baseUrl is not necessary in production
baseUrl: ENVIRONMENT === "development"
? "https://<YOUR_NGROK_OR_TUNNEL_URL>/"
: undefined,
}
)
return await handler(c)
})
export default app
-
Deployment: Deploy your Hono app to production as you normally would, for example using the Cloudflare CLI:
Terminalwrangler deploy
-
Verify Workflow Endpoint: After deployment, verify that your workflow endpoint is accessible by making a POST request to your production URL:
Terminalcurl -X POST https://<YOUR-PRODUCTION-URL>/workflow
-
Monitor in QStash Dashboard: Use the QStash dashboard to monitor your production workflows. You can track workflow runs, view step statuses, and access detailed logs.
-
Set Up Alerts: Consider setting up alerts in Sentry or other monitoring tools to be notified of any workflow failures in production.
Next Steps
-
Learn how to protect your workflow endpoint from unauthorized access by securing your workflow endpoint.
-
Explore our Hono example for a detailed, end-to-end example and best practices.
-
For setting up and testing your workflows in a local environment, check out our local development guide.
Was this page helpful?