> ## Documentation Index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Hono

<Card title="GitHub Repository" icon="github" href="https://github.com/upstash/workflow-js/tree/main/examples/hono" horizontal>
  You can find the project source code on GitHub.
</Card>

<Card title="Deploy With Cloudflare Workers" icon="cloudflare" href="https://deploy.workers.cloudflare.com/?url=https://github.com/upstash/qstash-workflow-example-cloudflare-workers-hono" horizontal>
  Deploy the project to Cloudflare Workers with a single click.
</Card>

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](https://github.com/upstash/workflow-js/tree/main/examples/hono) for a detailed, end-to-end example and best practices.

## Prerequisites

1. An Upstash QStash API key.
2. 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](https://console.upstash.com/login) for an Upstash account and navigating to your QStash dashboard.

## Step 1: Installation

First, install the Workflow SDK in your Hono project:

<Tabs>
  <Tab title="npm">
    ```bash theme={"system"}
    npm install @upstash/workflow
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={"system"}
    pnpm install @upstash/workflow
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={"system"}
    bun add @upstash/workflow
    ```
  </Tab>
</Tabs>

## 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.

```bash Terminal theme={"system"}
touch .dev.vars
```

Upstash Workflow is powered by [QStash](/qstash/overall/getstarted), which requires access to your endpoint to execute workflows. When your app is deployed, QStash will use the app's URL. However, for local development, you have two main options: [use a local QStash server or set up a local tunnel](/workflow/howto/local-development).

### Option 1: Local QStash Server

To start the local QStash server, run:

```bash theme={"system"}
npx @upstash/qstash-cli dev
```

Once the command runs successfully, you’ll see `QSTASH_URL` and `QSTASH_TOKEN` values in the console. Add these values to your `.dev.vars` file:

```txt .dev.vars theme={"system"}
QSTASH_URL="http://127.0.0.1:8080"
QSTASH_TOKEN="<QSTASH_TOKEN>"
```

This approach allows you to test workflows locally without affecting your billing. However, runs won't be logged in the Upstash Console.

### Option 2: Local Tunnel

Alternatively, you can set up a local tunnel. For this option:

1. Copy the `QSTASH_TOKEN` from the Upstash Console.
2. Update your `.dev.vars` file with the following:

```txt .dev.vars theme={"system"}
QSTASH_TOKEN="***"
UPSTASH_WORKFLOW_URL="<UPSTASH_WORKFLOW_URL>"
```

* Replace `***` with your actual QStash token.
* Set `UPSTASH_WORKFLOW_URL` to the public URL provided by your local tunnel.

Here’s where you can find your QStash token:

<Frame>
  <img src="https://mintcdn.com/upstash/V1WwT580M-elE8rq/img/qstash-workflow/qstash_token.png?fit=max&auto=format&n=V1WwT580M-elE8rq&q=85&s=df12ba48119bcdd13a675e53b43ab74d" width="1211" height="833" data-path="img/qstash-workflow/qstash_token.png" />
</Frame>

Using a local tunnel connects your endpoint to the production QStash, enabling you to view workflow logs in the Upstash Console.

## 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:

<Tabs>
  <Tab title="Minimal example">
    ```typescript src/index.ts theme={"system"}
    import { Hono } from "hono"
    import { serve } from "@upstash/workflow/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
    ```
  </Tab>

  <Tab title="With Hono context">
    ```typescript src/index.ts theme={"system"}
    import { Hono } from "hono"
    import { serve, WorkflowBindings } from "@upstash/workflow/hono"
    import { env } from "hono/adapter"

    interface Bindings extends WorkflowBindings {
      ENVIRONMENT: "development" | "production"
    }

    const app = new Hono<{ Bindings: Bindings }>()

    app.post("/workflow", (c) => {
      // 👇 access Honos native context, i.e. getting an env variable
      const { ENVIRONMENT } = env(c)

      // 👇 `unknown` represents your initial payload data type
      const handler = serve<unknown, Bindings>(
        async (context) => { ... }
      )

      return await handler(c)
    })

    export default app
    ```
  </Tab>
</Tabs>

## Step 4: Run the Workflow Endpoint

To start your Hono app locally, run the following command:

```bash Terminal theme={"system"}
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:

<Frame>
  <img src="https://mintcdn.com/upstash/V1WwT580M-elE8rq/img/qstash-workflow/wrangler.png?fit=max&auto=format&n=V1WwT580M-elE8rq&q=85&s=707cec511359835449c86699cb91de29" width="1122" height="524" data-path="img/qstash-workflow/wrangler.png" />
</Frame>

Then, make a POST request to your workflow endpoint. For each workflow run, a unique workflow run ID is returned:

```bash Terminal theme={"system"}
curl -X POST https://localhost:8787/workflow

# result: {"workflowRunId":"wfr_xxxxxx"}
```

See the [documentation on starting a workflow](/workflow/howto/start) for other ways you can start your workflow.

<Frame>
  <img src="https://mintcdn.com/upstash/V1WwT580M-elE8rq/img/qstash-workflow/hono_local_request.png?fit=max&auto=format&n=V1WwT580M-elE8rq&q=85&s=e53201dceb3377bf5c88b05740dddc42" width="1756" height="639" data-path="img/qstash-workflow/hono_local_request.png" />
</Frame>

If you didn't set up local QStash development server, you can 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.

<Frame>
  <img src="https://mintcdn.com/upstash/pqZtv0gXFMQuy8rU/img/qstash-workflow/dashboard.png?fit=max&auto=format&n=pqZtv0gXFMQuy8rU&q=85&s=d62fa91b9bcfc9c845105c42dae6f1e0" width="1656" height="1080" data-path="img/qstash-workflow/dashboard.png" />
</Frame>

## 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:

1. **Environment Variables**: Make sure that all necessary environment variables from your `.dev.vars` file are set in your Cloudflare Worker project settings. For example, your `QSTASH_TOKEN`, and any other configuration variables your workflow might need.

2. **Remove Local Development Settings**: In your production code, you can remove or conditionally exclude any local development settings. For example, if you used [local tunnel for local development](/workflow/howto/local-development#local-tunnel-with-ngrok)

3. **Deployment**: Deploy your Hono app to production as you normally would, for example using the Cloudflare CLI:

   ```bash Terminal theme={"system"}
   wrangler deploy
   ```

4. **Verify Workflow Endpoint**: After deployment, verify that your workflow endpoint is accessible by making a POST request to your production URL:

   ```bash Terminal theme={"system"}
   curl -X POST https://<YOUR-PRODUCTION-URL>/workflow
   ```

5. **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.

6. **Set Up Alerts**: Consider setting up alerts in Sentry or other monitoring tools to be notified of any workflow failures in production.

## Next Steps

1. Learn how to protect your workflow endpoint from unauthorized access by [securing your workflow endpoint](/workflow/howto/security).

2. Explore [the source code](https://github.com/upstash/workflow-js/tree/main/examples/hono) for a detailed, end-to-end example and best practices.

3. For setting up and testing your workflows in a local environment, check out our [local development guide](/workflow/howto/local-development).