feat(hono)!: Change setup for @sentry/hono/node (init in external file) (#20497)

Let's users set up Sentry in an external file. This makes it easier to
filter any integrations. The setup is now slightly different than it is
for Bun and Cloudflare, but the Node runtime just works differently.

Closes  #20460

BREAKING CHANGE: `sentry` from `@sentry/hono/node` does not accept
`options` anymore as those need to be passed in a separate
`Sentry.init()` that is called in an external file:
```ts
// instrument.mjs (or instrument.ts)
import * as Sentry from '@sentry/hono/node';

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

Author: s1gr1d

dev-packages/e2e-tests/test-applications/hono-4/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "scripts": {
     "dev:cf": "wrangler dev --var \"E2E_TEST_DSN:$E2E_TEST_DSN\" --log-level=$(test $CI && echo 'none' || echo 'log')",
-    "dev:node": "node --import tsx/esm --import @sentry/node/preload src/entry.node.ts",
+    "dev:node": "node --import tsx/esm --import ./src/instrument.node.ts src/entry.node.ts",
     "dev:bun": "bun src/entry.bun.ts",
     "build": "wrangler deploy --dry-run",
     "test:build": "pnpm install && pnpm build",

dev-packages/e2e-tests/test-applications/hono-4/src/entry.node.ts

@@ -3,17 +3,9 @@ import { sentry } from '@sentry/hono/node';
 import { serve } from '@hono/node-server';
 import { addRoutes } from './routes';
 
-const app = new Hono<{ Bindings: { E2E_TEST_DSN: string } }>();
+const app = new Hono();
 
-app.use(
-  // @ts-expect-error - Env is not yet in type
-  sentry(app, {
-    dsn: process.env.E2E_TEST_DSN,
-    environment: 'qa',
-    tracesSampleRate: 1.0,
-    tunnel: 'http://localhost:3031/',
-  }),
-);
+app.use(sentry(app));
 
 addRoutes(app);
 

dev-packages/e2e-tests/test-applications/hono-4/src/instrument.node.ts

@@ -0,0 +1,8 @@
+import * as Sentry from '@sentry/hono/node';
+
+Sentry.init({
+  dsn: process.env.E2E_TEST_DSN,
+  environment: 'qa',
+  tracesSampleRate: 1.0,
+  tunnel: 'http://localhost:3031/',
+});

dev-packages/e2e-tests/test-applications/hono-4/tests/constants.ts

@@ -1,6 +1,5 @@
 export type Runtime = 'cloudflare' | 'node' | 'bun';
 
 export const RUNTIME = (process.env.RUNTIME || 'cloudflare') as Runtime;
-export const isNode = RUNTIME === 'node';
 
 export const APP_NAME = 'hono-4';

dev-packages/e2e-tests/test-applications/hono-4/tests/middleware.test.ts

@@ -1,27 +1,20 @@
 import { expect, test } from '@playwright/test';
 import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 import { type SpanJSON } from '@sentry/core';
-import { APP_NAME, isNode } from './constants';
-
-// In Node, @sentry/node/preload eagerly activates the OTel HonoInstrumentation,
-// which wraps all Hono instance methods at construction time via WrappedHono.
-const MIDDLEWARE_ORIGIN = 'auto.middleware.hono';
-const OTEL_ORIGIN = 'auto.http.otel.hono';
+import { APP_NAME } from './constants';
 
 const SCENARIOS = [
   {
     name: 'root app middleware',
     prefix: '/test-middleware',
-    origin: MIDDLEWARE_ORIGIN,
   },
   {
     name: 'sub-app middleware (route group)',
     prefix: '/test-subapp-middleware',
-    origin: isNode ? OTEL_ORIGIN : MIDDLEWARE_ORIGIN,
   },
 ] as const;
 
-for (const { name, prefix, origin } of SCENARIOS) {
+for (const { name, prefix } of SCENARIOS) {
   test.describe(name, () => {
     test('creates a span for named middleware', async ({ baseURL }) => {
       const transactionPromise = waitForTransaction(APP_NAME, event => {
@@ -43,7 +36,7 @@ for (const { name, prefix, origin } of SCENARIOS) {
         expect.objectContaining({
           description: 'middlewareA',
           op: 'middleware.hono',
-          origin,
+          origin: 'auto.middleware.hono',
           status: 'ok',
         }),
       );
@@ -68,18 +61,13 @@ for (const { name, prefix, origin } of SCENARIOS) {
         expect.objectContaining({
           description: '<anonymous>',
           op: 'middleware.hono',
-          origin: MIDDLEWARE_ORIGIN,
+          origin: 'auto.middleware.hono',
           status: 'ok',
         }),
       );
     });
 
     test('multiple middleware are sibling spans under the same parent', async ({ baseURL }) => {
-      test.skip(
-        isNode,
-        'Node double-instruments middleware (too many spans) - TODO: fix this in the SDK and re-enable the test',
-      );
-
       const transactionPromise = waitForTransaction(APP_NAME, event => {
         return event.contexts?.trace?.op === 'http.server' && event.transaction === `GET ${prefix}/multi`;
       });
@@ -90,7 +78,6 @@ for (const { name, prefix, origin } of SCENARIOS) {
       const transaction = await transactionPromise;
       const spans = transaction.spans || [];
 
-      // Sort spans because they are in a different order in Node/Bun (OTel-based)
       const middlewareSpans = spans.sort((a, b) => (a.start_timestamp ?? 0) - (b.start_timestamp ?? 0));
 
       expect(middlewareSpans).toHaveLength(2);
@@ -139,10 +126,6 @@ for (const { name, prefix, origin } of SCENARIOS) {
       const transaction = await transactionPromise;
       const spans = transaction.spans || [];
 
-      // On the /error path only one middleware (failingMiddleware) is registered,
-      // so we can find the error span by status alone. On Node for sub-apps, the
-      // OTel layer wraps before patchRoute, so the function name may be lost in
-      // the patchRoute span — but the error status is always set.
       const failingSpan = spans.find(
         (span: SpanJSON) => span.op === 'middleware.hono' && span.status === 'internal_error',
       );
@@ -169,36 +152,8 @@ for (const { name, prefix, origin } of SCENARIOS) {
   });
 }
 
-test.describe('.all() handler on sub-app (method ALL edge case)', () => {
-  test('Node: OTel wraps .all() and produces a hono span', async ({ baseURL }) => {
-    test.skip(!isNode, 'Node-specific: OTel wraps .all() at construction time');
-
-    const transactionPromise = waitForTransaction(APP_NAME, event => {
-      return (
-        event.contexts?.trace?.op === 'http.server' && event.transaction === 'GET /test-subapp-middleware/all-handler'
-      );
-    });
-
-    const response = await fetch(`${baseURL}/test-subapp-middleware/all-handler`);
-    expect(response.status).toBe(200);
-
-    const body = await response.json();
-    expect(body).toEqual({ handler: 'all' });
-
-    const transaction = await transactionPromise;
-    const spans = transaction.spans || [];
-
-    // On Node, OTel wraps .all() at construction time. Since the handler
-    // returns a Response, OTel classifies it as 'request_handler' (not
-    // middleware). patchRoute also wraps it but sees the anonymous OTel wrapper.
-    // Either way, the handler IS instrumented — verify any hono span exists.
-    const honoSpan = spans.find((span: SpanJSON) => span.op?.endsWith('.hono'));
-    expect(honoSpan).toBeDefined();
-  });
-
-  test('Bun/Cloudflare: patchRoute wraps .all() as middleware span', async ({ baseURL }) => {
-    test.skip(isNode, 'Bun/Cloudflare-specific: patchRoute is the sole wrapper');
-
+test.describe('patchRoute wraps .all() as middleware span (in sub-app)', () => {
+  test('patchRoute wraps .all() as middleware span', async ({ baseURL }) => {
     const transactionPromise = waitForTransaction(APP_NAME, event => {
       return (
         event.contexts?.trace?.op === 'http.server' && event.transaction === 'GET /test-subapp-middleware/all-handler'
@@ -225,7 +180,7 @@ test.describe('.all() handler on sub-app (method ALL edge case)', () => {
       expect.objectContaining({
         description: 'allCatchAll',
         op: 'middleware.hono',
-        origin: MIDDLEWARE_ORIGIN,
+        origin: 'auto.middleware.hono',
         status: 'ok',
       }),
     );

dev-packages/node-integration-tests/suites/hono-sdk/instrument.mjs

@@ -1 +1,8 @@
-// Sentry is initialized by the @sentry/hono/node middleware in scenario.mjs
+import * as Sentry from '@sentry/hono/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+});

dev-packages/node-integration-tests/suites/hono-sdk/scenario.mjs

@@ -1,17 +1,11 @@
 import { serve } from '@hono/node-server';
 import { sentry } from '@sentry/hono/node';
-import { loggingTransport, sendPortToRunner } from '@sentry-internal/node-integration-tests';
+import { sendPortToRunner } from '@sentry-internal/node-integration-tests';
 import { Hono } from 'hono';
 
 const app = new Hono();
 
-app.use(
-  sentry(app, {
-    dsn: 'https://public@dsn.ingest.sentry.io/1337',
-    tracesSampleRate: 1.0,
-    transport: loggingTransport,
-  }),
-);
+app.use(sentry(app));
 
 app.get('/', c => {
   return c.text('Hello from Hono on Node!');

packages/hono/README.md

@@ -33,7 +33,7 @@ npm install @sentry/hono
 
 Additionally to `@sentry/hono`, install the `@sentry/cloudflare` package:
 
-```bashbash
+```bash
 npm install --save @sentry/cloudflare
 ```
 
@@ -100,62 +100,68 @@ export default app;
 
 Additionally to `@sentry/hono`, install the `@sentry/node` package:
 
-```bashbash
+```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 your Hono app
+### 2. Initialize Sentry in a separate file
 
-Initialize the Sentry Hono middleware as early as possible in your app:
+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
-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
+// instrument.mjs (or instrument.ts)
+import * as Sentry from '@sentry/hono/node';
 
-serve(app);
+Sentry.init({
+  dsn: '__DSN__',
+  tracesSampleRate: 1.0,
+});
 ```
 
-### 3. Add `preload` script to start command
-
-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.
+### 3. Load the instrument file with `--import`
 
-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:
+When starting your Hono Node application, use the `--import` CLI flag to load `instrument.mjs` before your app code:
 
 ```bash
-node --import @sentry/node/preload index.js
+node --import ./instrument.mjs app.js
 ```
 
 This option can also be added to the `NODE_OPTIONS` environment variable:
 
 ```bash
-NODE_OPTIONS="--import @sentry/node/preload"
+NODE_OPTIONS="--import ./instrument.mjs"
 ```
 
-Read more about this preload script in the docs: https://docs.sentry.io/platforms/javascript/guides/hono/install/late-initialization/#late-initialization-with-esm
+### 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:
 
-```bashbash
+```bash
 npm install --save @sentry/bun
 ```
 

packages/hono/src/node/middleware.ts

@@ -1,20 +1,28 @@
-import { type BaseTransportOptions, debug, type Options } from '@sentry/core';
-import { init } from './sdk';
+import { type BaseTransportOptions, debug, type Options, getClient } from '@sentry/core';
 import type { Hono, MiddlewareHandler } from 'hono';
 import { requestHandler, responseHandler } from '../shared/middlewareHandlers';
 import { applyPatches } from '../shared/applyPatches';
 
 export interface HonoNodeOptions extends Options<BaseTransportOptions> {}
 
 /**
- * Sentry middleware for Hono running in a Node runtime environment.
+ * Sentry middleware for Hono applications running in a Node.js environment.
+ *
+ * This middleware enhances your Hono application by automatically instrumenting incoming requests and outgoing responses.
+ * It also applies the necessary patches to ensure Sentry captures execution context correctly in Node.js.
+ *
+ * **Note:** You must initialize Sentry separately before using this middleware. Typically, this is done by calling `Sentry.init()` in an `instrument.ts` file and loading it via the Node `--import` flag.
  */
-export const sentry = (app: Hono, options: HonoNodeOptions): MiddlewareHandler => {
-  const isDebug = options.debug;
-
-  isDebug && debug.log('Initialized Sentry Hono middleware (Node)');
-
-  init(options);
+export const sentry = (app: Hono): MiddlewareHandler => {
+  const sentryClient = getClient();
+  if (sentryClient === undefined) {
+    debug.warn(
+      'Sentry is not initialized. Call `init()` from @sentry/hono/node in an `instrument.ts` file loaded via `--import` to set up Sentry for your application.',
+    );
+  } else {
+    sentryClient.getOptions().debug &&
+      debug.log('Sentry is initialized, proceeding to set up Hono `sentry` middleware.');
+  }
 
   applyPatches(app);
 

packages/hono/src/node/sdk.ts

@@ -1,20 +1,23 @@
 import type { Client } from '@sentry/core';
-import { applySdkMetadata } from '@sentry/core';
+import { applySdkMetadata, debug, getClient } from '@sentry/core';
 import { init as initNode } from '@sentry/node';
 import type { HonoNodeOptions } from './middleware';
 import { buildFilteredIntegrations } from '../shared/buildFilteredIntegrations';
 
 /**
  * Initializes Sentry for Hono running in a Node runtime environment.
  *
- * In general, it is recommended to initialize Sentry via the `sentry()` middleware, as it sets up everything by default and calls `init` internally.
- *
- * When manually calling `init`, add the `honoIntegration` to the `integrations` array to set up the Hono integration.
+ * This function should be called in an `instrument.ts` file loaded via `--import` to set up Sentry globally for the application.
  */
 export function init(options: HonoNodeOptions): Client | undefined {
+  const existingClient = getClient();
+  if (existingClient) {
+    existingClient.getOptions().debug && debug.log('Sentry is already initialized, skipping re-initialization.');
+    return existingClient;
+  }
+
   applySdkMetadata(options, 'hono', ['hono', 'node']);
 
-  // Remove Hono from the SDK defaults to prevent double instrumentation: @sentry/node
   const filteredOptions: HonoNodeOptions = {
     ...options,
     integrations: buildFilteredIntegrations(options.integrations, false),