This SDK is compatible with Hono 4+ and is currently in ALPHA. Alpha features are still in progress, may have bugs and might include breaking changes. Please reach out on GitHub if you have any feedback or concerns.

• General SDK Docs - Official Docs for this Hono SDK are coming soon!

The current Hono SDK Docs explain using Sentry in Hono by using other Sentry SDKs (e.g. @sentry/node or @sentry/cloudflare)

To get started, first install the @sentry/hono package:

npm install @sentry/hono

Set the nodejs_compat compatibility flag in your wrangler.jsonc/wrangler.toml config. This is because the SDK needs access to the AsyncLocalStorage API to work correctly.

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

compatibility_flags = ["nodejs_compat"]

Initialize the Sentry Hono middleware as early as possible in your app:

import { Hono } from 'hono';
import { sentry } from '@sentry/hono/cloudflare';

const app = new Hono();

// Initialize Sentry middleware right after creating the app
app.use(
  sentry(app, {
    dsn: '__DSN__',
    // ...other Sentry options
  }),
);

// ... your routes and other middleware

export default app;

Pass the options as a callback instead of a plain options object. The function receives the Cloudflare Worker env as defined in the Worker's Bindings:

import { Hono } from 'hono';
import { sentry } from '@sentry/hono/cloudflare';

type Bindings = { SENTRY_DSN: string };

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

app.use(sentry(app, env => ({ dsn: env.SENTRY_DSN })));

export default app;

Initialize the Sentry Hono middleware as early as possible in your app:

import { Hono } from 'hono';
import { serve } from '@hono/node-server';
import { sentry } from '@sentry/hono/node';

const app = new Hono();

// Initialize Sentry middleware right after creating the app
app.use(
  sentry(app, {
    dsn: '__DSN__', // or process.env.SENTRY_DSN
    tracesSampleRate: 1.0,
  }),
);

// ... your routes and other middleware

serve(app);

To ensure that Sentry can capture spans from third-party libraries (e.g. database clients) used in your Hono app, Sentry needs to wrap these libraries as early as possible.

When starting the Hono Node application, use the @sentry/node/preload hook with the --import CLI option to ensure modules are wrapped before the application code runs:

node --import @sentry/node/preload index.js

This option can also be added to the NODE_OPTIONS environment variable:

NODE_OPTIONS="--import @sentry/node/preload"

Read more about this preload script in the docs: https://docs.sentry.io/platforms/javascript/guides/hono/install/late-initialization/#late-initialization-with-esm