From fa88748866a505c849e919e5435b35a972e610f7 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Wed, 23 Sep 2026 10:53:11 +0200 Subject: [PATCH] docs(hono): Point README to SDK documentation Co-Authored-By: GPT-6 --- packages/hono/README.md | 245 ++-------------------------------------- 1 file changed, 8 insertions(+), 237 deletions(-) diff --git a/packages/hono/README.md b/packages/hono/README.md index 9506a20bdaba..2bb15d1ca93d 100644 --- a/packages/hono/README.md +++ b/packages/hono/README.md @@ -10,244 +10,15 @@ [![npm dm](https://img.shields.io/npm/dm/@sentry/hono.svg)](https://www.npmjs.com/package/@sentry/hono) [![npm dt](https://img.shields.io/npm/dt/@sentry/hono.svg)](https://www.npmjs.com/package/@sentry/hono) -This SDK is compatible with Hono 4+. +The official Sentry SDK for monitoring Hono applications. -## Links +## Documentation -- [Official SDK Docs](https://docs.sentry.io/platforms/javascript/guides/hono/) +- [Getting started](https://docs.sentry.io/platforms/javascript/guides/hono/) +- [Configuration](https://docs.sentry.io/platforms/javascript/guides/hono/configuration/) +- [Hono-specific features](https://docs.sentry.io/platforms/javascript/guides/hono/features/) -## Install +## Support -To get started, first install the `@sentry/hono` package: - -```bash -npm install @sentry/hono -``` - -## Setup (Cloudflare Workers) - -### 1. Install Peer Dependency - -Additionally to `@sentry/hono`, install the `@sentry/cloudflare` package: - -```bash -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. - -```jsonc {tabTitle:JSON} {filename:wrangler.jsonc} -{ - "compatibility_flags": ["nodejs_compat"], -} -``` - -```toml {tabTitle:Toml} {filename:wrangler.toml} -compatibility_flags = ["nodejs_compat"] -``` - -### 3. Initialize Sentry in your Hono app - -Initialize the Sentry Hono middleware as early as possible in your app: - -```typescript -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`: - -```typescript -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: - -```bash -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: - -```ts -// 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: - -```bash -node --import ./instrument.mjs app.js -``` - -This option can also be added to the `NODE_OPTIONS` environment variable: - -```bash -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: - -```ts -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: - -```bash -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: - -```ts -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); -``` - -## Setup (Deno) - -### 1. Install Peer Dependency - -Additionally to `@sentry/hono`, install the `@sentry/deno` package: - -```bash -npm install --save @sentry/deno -``` - -Make sure the installed version always stays in sync. The `@sentry/deno` package is a required peer dependency when using `@sentry/hono/deno`. -You won't import `@sentry/deno` 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, then serve it with `Deno.serve`: - -```ts -import { Hono } from 'hono'; -import { sentry } from '@sentry/hono/deno'; - -const app = new Hono(); - -// Initialize Sentry middleware right after creating the app -app.use( - sentry(app, { - dsn: '__DSN__', // or Deno.env.get('SENTRY_DSN') - tracesSampleRate: 1.0, - }), -); - -// ... your routes and other middleware - -Deno.serve(app.fetch); -``` - -Run your app with the permissions Sentry needs to read environment variables and send events: - -```bash -deno run --allow-net --allow-env --allow-read app.ts -``` - -## 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: - -```ts -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. +- [Report a bug](https://github.com/getsentry/sentry-javascript/issues/new/choose) +- [Contributing](https://github.com/getsentry/sentry-javascript/blob/develop/CONTRIBUTING.md)