Official Sentry SDK for Hono

This SDK is compatible with Hono 4+.

Links

• Official SDK Docs

Install

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

npm install @sentry/hono

Setup (Cloudflare Workers)

1. Install Peer Dependency

Additionally to @sentry/hono, install the @sentry/cloudflare package:

npm install --save @sentry/cloudflare

Make sure the installed version always stays in sync. The @sentry/cloudflare package is a required peer dependency when using @sentry/hono/cloudflare. You won't import @sentry/cloudflare directly in your code, but it needs to be installed in your project.

2. Enable Node.js compatibility

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"]

3. Initialize Sentry in your Hono app

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;

Access env from Cloudflare Worker bindings

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;

Setup (Node)

1. Install Peer Dependency

Additionally to @sentry/hono, install the @sentry/node package:

npm install --save @sentry/node

Make sure the installed version always stays in sync. The @sentry/node package is a required peer dependency when using @sentry/hono/node. You won't import @sentry/node directly in your code, but it needs to be installed in your project.

2. Initialize Sentry in a separate file

Create an instrument.mjs (or instrument.ts) file that initializes Sentry before the rest of your application runs. This ensures Sentry can wrap third-party libraries (e.g. database clients) as early as possible:

// instrument.mjs (or instrument.ts)
import * as Sentry from '@sentry/hono/node';

Sentry.init({
  dsn: '__DSN__',
  tracesSampleRate: 1.0,
});

3. Load the instrument file with --import

When starting your Hono Node application, use the --import CLI flag to load instrument.mjs before your app code:

node --import ./instrument.mjs app.js

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

NODE_OPTIONS="--import ./instrument.mjs"

4. Add the Sentry middleware to your Hono app

Add the sentry middleware to your Hono app. Since Sentry was already initialized in the instrument file, no options are passed here:

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

const app = new Hono();

// Add Sentry middleware right after creating the app
app.use(sentry(app));

// ... your routes and other middleware

serve(app);

Setup (Bun)

1. Install Peer Dependency

Additionally to @sentry/hono, install the @sentry/bun package:

npm install --save @sentry/bun

Make sure the installed version always stays in sync. The @sentry/bun package is a required peer dependency when using @sentry/hono/bun. You won't import @sentry/bun directly in your code, but it needs to be installed in your project.

2. Initialize Sentry in your Hono 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/bun';

const app = new Hono();

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

// ... your routes and other middleware

serve(app);

Filtering errors

By default, @sentry/hono captures 5xx errors and plain Error objects, and ignores 3xx/4xx HTTP errors (redirects, not-found, bad request, etc.).

Use shouldHandleError to override this on a per-error basis:

app.use(
  sentry(app, {
    dsn: '__DSN__',
    shouldHandleError(error) {
      const status = (error as { status?: number })?.status;
      // Capture 401/403 in addition to the default 5xx errors
      return status === 401 || status === 403 || typeof status !== 'number' || status >= 500;
    },
  }),
);

Return true to capture the error, false to suppress it.