Hono on Cloudflare

Step 1: Install

Choose the features you want to configure, and this guide will show you how:

Install the Sentry SDK

Run the command for your preferred package manager to add the Sentry SDK to your application:

npm install @sentry/cloudflare --save

Step 2: Configure

The main Sentry configuration should happen as early as possible in your app's lifecycle.

Wrangler Configuration

Since the SDK needs access to the AsyncLocalStorage API, you need to set the nodejs_compat compatibility flag in your wrangler.(jsonc|toml) configuration file:

{
  "compatibility_flags": ["nodejs_compat"],
}

Release Configuration (Optional)

If you don't set the release option manually, the SDK automatically detects it from these sources (in order of priority):

1. The SENTRY_RELEASE environment variable
2. The CF_VERSION_METADATA.id binding (if configured)

To enable automatic release detection via Cloudflare's version metadata, add the CF_VERSION_METADATA binding in your wrangler configuration. This provides access to the Cloudflare version metadata:

Sentry.withSentry(
  (env) => ({
    dsn: "___PUBLIC_DSN___",
    release: env.CF_VERSION_METADATA?.id,
  }),
  // ...
);

{
  // ...
  "version_metadata": {
    "binding": "CF_VERSION_METADATA"
  }
}

Initialize the Sentry SDK

Wrap your Hono app with the withSentry function, for example, in your index.ts file, to initialize the Sentry SDK and hook into the environment:

import { Env, Hono } from "hono";
import * as Sentry from "@sentry/cloudflare";

const app = new Hono();

// Add your routes here
// app.get('/your-route', (c) => c.text('Hello!'));

export default Sentry.withSentry(
  (env: Env) => ({
    dsn: "___PUBLIC_DSN___",

    // Adds request headers and IP for users, for more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#sendDefaultPii
    sendDefaultPii: true,
    // ___PRODUCT_OPTION_START___ logs

    // Enable logs to be sent to Sentry
    enableLogs: true,
    // ___PRODUCT_OPTION_END___ logs
    // ___PRODUCT_OPTION_START___ performance

    // Set tracesSampleRate to 1.0 to capture 100% of spans for tracing.
    // Learn more at
    // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#tracesSampleRate
    tracesSampleRate: 1.0,
    // ___PRODUCT_OPTION_END___ performance
  }),
  app,
);

Migration from Community Middleware

If you're currently using the @hono/sentry middleware, migrate to the official @sentry/cloudflare middleware:

// New approach using official Sentry SDK
import { Hono } from 'hono';
import * as Sentry from '@sentry/cloudflare';

const app = new Hono();

// Wrap your app with Sentry
export default Sentry.withSentry(
  (env: Env) => ({
    dsn: '___PUBLIC_DSN___',
    tracesSampleRate: 1.0,
  }),
  app
);

Report Unhandled Exceptions

By default, Sentry reports exceptions reported by the onError function from Hono. In case the error comes with a status code, it captures all errors except for the ones with a 3xx or 4xx status code.

To learn how to customize this behavior, see the honoIntegration documentation.

Step 3: Add Readable Stack Traces With Source Maps (Optional)

The stack traces in your Sentry errors probably won't look like your actual code. To fix this, upload your source maps to Sentry. The easiest way to do this is by using the Sentry Wizard:

npx @sentry/wizard@latest -i sourcemaps

Step 4: Verify Your Setup

Issues

First, let's verify that Sentry captures errors and creates issues in your Sentry project. Add the following code snippet to your main application file, adding a route that triggers an error that Sentry will capture:

app.get("/debug-sentry", () => {
  throw new Error("My first Sentry error!");
});

app.get("/debug-sentry", async () => {
  await Sentry.startSpan(
    {
      op: "test",
      name: "My First Test Transaction",
    },
    async () => {
      await new Promise((resolve) => setTimeout(resolve, 100)); // Wait for 100ms
      throw new Error("My first Sentry error!");
    },
  );
});

Next Steps

At this point, you should have integrated Sentry and should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:

• Learn how to manually capture errors
• Continue to customize your configuration
• Make use of Cloudflare-specific features
• Get familiar with Sentry's product features like tracing, insights, and alerts