feat(node): Register ESM patching hooks in init for supported Node.js versions

dev-packages/rollup-utils/code/otelEsmLoaderHookTemplate.js

@@ -1,2 +1,4 @@
 import { getFormat, getSource, load, resolve } from '@opentelemetry/instrumentation/hook.mjs';
 export { getFormat, getSource, load, resolve };
+
+globalThis._sentrySkipLoaderHookWarning = true;

packages/astro/src/server/sdk.ts

@@ -1,6 +1,7 @@
 import { applySdkMetadata } from '@sentry/core';
 import type { NodeOptions } from '@sentry/node';
 import { init as initNodeSdk, setTag } from '@sentry/node';
+import { GLOBAL_OBJ } from '@sentry/utils';
 
 /**
  *
@@ -12,6 +13,8 @@ export function init(options: NodeOptions): void {
   };
   applySdkMetadata(opts, 'astro', ['astro', 'node']);
 
+  GLOBAL_OBJ._sentrySkipLoaderHookWarning = true;
+
   initNodeSdk(opts);
 
   setTag('runtime', 'node');

packages/google-cloud-serverless/src/sdk.ts

@@ -2,6 +2,7 @@ import type { NodeOptions } from '@sentry/node';
 import { SDK_VERSION, getDefaultIntegrations as getDefaultNodeIntegrations, init as initNode } from '@sentry/node';
 import type { Integration, Options, SdkMetadata } from '@sentry/types';
 
+import { GLOBAL_OBJ } from '@sentry/utils';
 import { googleCloudGrpcIntegration } from './integrations/google-cloud-grpc';
 import { googleCloudHttpIntegration } from './integrations/google-cloud-http';
 

packages/nextjs/src/server/index.ts

@@ -86,6 +86,8 @@ export function init(options: NodeOptions): void {
     return;
   }
 
+  GLOBAL_OBJ._sentrySkipLoaderHookWarning = true;
+
   const customDefaultIntegrations = [
     ...getDefaultIntegrations(options).filter(
       integration =>

packages/node/src/sdk/init.ts

@@ -14,6 +14,7 @@ import {
 import { openTelemetrySetupCheck, setOpenTelemetryContextAsyncContextStrategy } from '@sentry/opentelemetry';
 import type { Client, Integration, Options } from '@sentry/types';
 import {
+  GLOBAL_OBJ,
   consoleSandbox,
   dropUndefinedKeys,
   logger,
@@ -25,6 +26,7 @@ import { consoleIntegration } from '../integrations/console';
 import { nodeContextIntegration } from '../integrations/context';
 import { contextLinesIntegration } from '../integrations/contextlines';
 
+import moduleModule from 'module';
 import { httpIntegration } from '../integrations/http';
 import { localVariablesIntegration } from '../integrations/local-variables';
 import { modulesIntegration } from '../integrations/modules';
@@ -90,13 +92,20 @@ export function init(options: NodeOptions | undefined = {}): void {
   }
 
   if (!isCjs()) {
-    // We want to make sure users see this warning
-    consoleSandbox(() => {
-      // eslint-disable-next-line no-console
-      console.warn(
-        '[Sentry] You are using the Sentry SDK with an ESM build. This version of the SDK is not compatible with ESM. Please either build your application with CommonJS, or use v7 of the SDK.',
-      );
-    });
+    const [nodeMajor, nodeMinor] = process.versions.node.split('.').map(Number);
+
+    // Register hook was added in v20.6.0 and v18.19.0
+    if (nodeMajor > 22 || (nodeMajor === 20 && nodeMinor >= 6) || (nodeMajor === 18 && nodeMinor >= 19)) {
+      // @ts-expect-error register is available in these versions & import.meta is allowed
+      moduleModule.register('@opentelemetry/instrumentation/hook.mjs', import.meta.url);
+    } else if (!GLOBAL_OBJ._sentrySkipLoaderHookWarning) {
+      consoleSandbox(() => {
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[Sentry] You are using the Sentry SDK in combination with an older version (pre 18.19.0 or pre 20.6.0) of Node.js in ESM mode. For the Sentry SDK to operate properly, please run your Node.js application with a `--loader=@sentry/node/loader` flag. For example: `node --loader=@sentry/node/loader your-app.js`',
+        );
+      });
+    }
   }
 
   setOpenTelemetryContextAsyncContextStrategy();

packages/remix/src/index.server.ts

@@ -1,7 +1,7 @@
 import { applySdkMetadata, isInitialized } from '@sentry/core';
 import type { NodeOptions } from '@sentry/node';
 import { init as nodeInit, setTag } from '@sentry/node';
-import { logger } from '@sentry/utils';
+import { GLOBAL_OBJ, logger } from '@sentry/utils';
 
 import { DEBUG_BUILD } from './utils/debug-build';
 import { instrumentServer } from './utils/instrumentServer';
@@ -131,6 +131,8 @@ export function init(options: RemixOptions): void {
     return;
   }
 
+  GLOBAL_OBJ._sentrySkipLoaderHookWarning = true;
+
   instrumentServer();
 
   nodeInit(options as NodeOptions);

packages/utils/src/worldwide.ts

@@ -66,6 +66,7 @@ export interface InternalGlobal {
    * Keys are `error.stack` strings, values are the metadata.
    */
   _sentryModuleMetadata?: Record<string, any>;
+  _sentrySkipLoaderHookWarning?: boolean;
 }
 
 /** Get's the global object for the current JavaScript runtime */