feat: Tidy existing loader hook

Author: timfish

packages/node-core/src/index.ts

@@ -35,7 +35,8 @@ export { getSentryRelease, defaultStackParser } from './sdk/api';
 export { createGetModuleFromFilename } from './utils/module';
 export { addOriginToSpan } from './utils/addOriginToSpan';
 export { getRequestUrl } from './utils/getRequestUrl';
-export { isCjs } from './utils/commonjs';
+export { initializeEsmLoader } from './sdk/esmLoader';
+export { isCjs } from './utils/detection';
 export { ensureIsWrapped } from './utils/ensureIsWrapped';
 export { createMissingInstrumentationContext } from './utils/createMissingInstrumentationContext';
 export { envToBool } from './utils/envToBool';

packages/node-core/src/integrations/modules.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import type { IntegrationFn } from '@sentry/core';
-import { isCjs } from '../utils/commonjs';
+import { isCjs } from '../utils/detection';
 
 type ModuleInfo = Record<string, string>;
 

packages/node-core/src/sdk/esmLoader.ts

@@ -1,31 +1,31 @@
-import { consoleSandbox, debug, GLOBAL_OBJ } from '@sentry/core';
+import { debug, GLOBAL_OBJ } from '@sentry/core';
 import { createAddHookMessageChannel } from 'import-in-the-middle';
-import moduleModule from 'module';
+import * as moduleModule from 'module';
+import { supportsEsmLoaderHooks } from '../utils/detection';
 
-/** Initialize the ESM loader. */
-export function maybeInitializeEsmLoader(): void {
-  const [nodeMajor = 0, nodeMinor = 0] = process.versions.node.split('.').map(Number);
+/**
+ * Initialize the ESM loader - This method is private and not part of the public
+ * API.
+ *
+ * @ignore
+ */
+export function initializeEsmLoader(): void {
+  if (!supportsEsmLoaderHooks()) {
+    return;
+  }
+
+  if (!GLOBAL_OBJ._sentryEsmLoaderHookRegistered) {
+    GLOBAL_OBJ._sentryEsmLoaderHookRegistered = true;
 
-  // Register hook was added in v20.6.0 and v18.19.0
-  if (nodeMajor >= 21 || (nodeMajor === 20 && nodeMinor >= 6) || (nodeMajor === 18 && nodeMinor >= 19)) {
-    if (!GLOBAL_OBJ._sentryEsmLoaderHookRegistered) {
-      try {
-        const { addHookMessagePort } = createAddHookMessageChannel();
-        // @ts-expect-error register is available in these versions
-        moduleModule.register('import-in-the-middle/hook.mjs', import.meta.url, {
-          data: { addHookMessagePort, include: [] },
-          transferList: [addHookMessagePort],
-        });
-      } catch (error) {
-        debug.warn('Failed to register ESM hook', error);
-      }
+    try {
+      const { addHookMessagePort } = createAddHookMessageChannel();
+      // @ts-expect-error register is available in these versions
+      moduleModule.register('import-in-the-middle/hook.mjs', import.meta.url, {
+        data: { addHookMessagePort, include: [] },
+        transferList: [addHookMessagePort],
+      });
+    } catch (error) {
+      debug.warn("Failed to register 'import-in-the-middle' hook", error);
     }
-  } else {
-    consoleSandbox(() => {
-      // eslint-disable-next-line no-console
-      console.warn(
-        `[Sentry] You are using Node.js v${process.versions.node} in ESM mode ("import syntax"). The Sentry Node.js SDK is not compatible with ESM in Node.js versions before 18.19.0 or before 20.6.0. Please either build your application with CommonJS ("require() syntax"), or upgrade your Node.js version.`,
-      );
-    });
   }
 }

packages/node-core/src/sdk/index.ts

@@ -35,11 +35,11 @@ import { INTEGRATION_NAME as SPOTLIGHT_INTEGRATION_NAME, spotlightIntegration }
 import { systemErrorIntegration } from '../integrations/systemError';
 import { makeNodeTransport } from '../transports';
 import type { NodeClientOptions, NodeOptions } from '../types';
-import { isCjs } from '../utils/commonjs';
+import { isCjs } from '../utils/detection';
 import { envToBool } from '../utils/envToBool';
 import { defaultStackParser, getSentryRelease } from './api';
 import { NodeClient } from './client';
-import { maybeInitializeEsmLoader } from './esmLoader';
+import { initializeEsmLoader } from './esmLoader';
 
 /**
  * Get default integrations for the Node-Core SDK.
@@ -106,8 +106,8 @@ function _init(
     }
   }
 
-  if (!isCjs() && options.registerEsmLoaderHooks !== false) {
-    maybeInitializeEsmLoader();
+  if (options.registerEsmLoaderHooks !== false) {
+    initializeEsmLoader();
   }
 
   setOpenTelemetryContextAsyncContextStrategy();
@@ -131,7 +131,7 @@ function _init(
 
   client.init();
 
-  debug.log(`Running in ${isCjs() ? 'CommonJS' : 'ESM'} mode.`);
+  debug.log(`SDK initialized from ${isCjs() ? 'CommonJS' : 'ESM'}`);
 
   client.startClientReportTracking();
 

packages/node-core/src/utils/commonjs.ts

@@ -1,5 +1,5 @@
 import type { MissingInstrumentationContext } from '@sentry/core';
-import { isCjs } from './commonjs';
+import { isCjs } from './detection';
 
 export const createMissingInstrumentationContext = (pkg: string): MissingInstrumentationContext => ({
   package: pkg,

packages/node-core/src/utils/createMissingInstrumentationContext.ts

@@ -0,0 +1,49 @@
+import * as moduleModule from 'node:module';
+import { consoleSandbox } from '@sentry/core';
+
+/** Detect CommonJS. */
+export function isCjs(): boolean {
+  try {
+    return typeof module !== 'undefined' && typeof module.exports !== 'undefined';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if the current Node.js version supports module.register
+ */
+export function supportsEsmLoaderHooks(): boolean {
+  logIfUnsupportedNodeVersion();
+
+  return 'register' in moduleModule;
+}
+
+let hasWarnedAboutNodeVersion: boolean | undefined;
+
+/**
+ * Log a warning if the current Node.js version is not supported in ESM mode
+ */
+function logIfUnsupportedNodeVersion(): void {
+  if (hasWarnedAboutNodeVersion) {
+    return;
+  }
+
+  if (isCjs()) {
+    return;
+  }
+
+  const [nodeMajor = 0, nodeMinor = 0] = process.versions.node.split('.').map(Number);
+  if (nodeMajor >= 21 || (nodeMajor === 20 && nodeMinor >= 6) || (nodeMajor === 18 && nodeMinor >= 19)) {
+    return;
+  }
+
+  hasWarnedAboutNodeVersion = true;
+
+  consoleSandbox(() => {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[Sentry] You are using Node.js v${process.versions.node} in ESM mode ("import syntax"). The Sentry Node.js SDK is not compatible with ESM in Node.js versions before 18.19.0 or before 20.6.0. Please either build your application with CommonJS ("require() syntax"), or upgrade your Node.js version.`,
+    );
+  });
+}

packages/node-core/src/utils/detection.ts

@@ -1,8 +1,8 @@
 import { isWrapped } from '@opentelemetry/instrumentation';
 import { consoleSandbox, getClient, getGlobalScope, hasSpansEnabled, isEnabled } from '@sentry/core';
 import type { NodeClient } from '../sdk/client';
-import { isCjs } from './commonjs';
 import { createMissingInstrumentationContext } from './createMissingInstrumentationContext';
+import { isCjs } from './detection';
 
 /**
  * Checks and warns if a framework isn't wrapped by opentelemetry.

packages/node-core/src/utils/ensureIsWrapped.ts

@@ -7,11 +7,9 @@ import {
   ATTR_SERVICE_VERSION,
   SEMRESATTRS_SERVICE_NAMESPACE,
 } from '@opentelemetry/semantic-conventions';
-import { consoleSandbox, debug as coreDebug, GLOBAL_OBJ, SDK_VERSION } from '@sentry/core';
-import { type NodeClient, isCjs, SentryContextManager, setupOpenTelemetryLogger } from '@sentry/node-core';
+import { debug as coreDebug, SDK_VERSION } from '@sentry/core';
+import { type NodeClient, initializeEsmLoader, SentryContextManager, setupOpenTelemetryLogger } from '@sentry/node-core';
 import { SentryPropagator, SentrySampler, SentrySpanProcessor } from '@sentry/opentelemetry';
-import { createAddHookMessageChannel } from 'import-in-the-middle';
-import moduleModule from 'module';
 import { DEBUG_BUILD } from '../debug-build';
 import { getOpenTelemetryInstrumentationToPreload } from '../integrations/tracing';
 
@@ -35,34 +33,6 @@ export function initOpenTelemetry(client: NodeClient, options: AdditionalOpenTel
   client.traceProvider = provider;
 }
 
-/** Initialize the ESM loader. */
-export function maybeInitializeEsmLoader(): void {
-  const [nodeMajor = 0, nodeMinor = 0] = process.versions.node.split('.').map(Number);
-
-  // Register hook was added in v20.6.0 and v18.19.0
-  if (nodeMajor >= 21 || (nodeMajor === 20 && nodeMinor >= 6) || (nodeMajor === 18 && nodeMinor >= 19)) {
-    if (!GLOBAL_OBJ._sentryEsmLoaderHookRegistered) {
-      try {
-        const { addHookMessagePort } = createAddHookMessageChannel();
-        // @ts-expect-error register is available in these versions
-        moduleModule.register('import-in-the-middle/hook.mjs', import.meta.url, {
-          data: { addHookMessagePort, include: [] },
-          transferList: [addHookMessagePort],
-        });
-      } catch (error) {
-        coreDebug.warn('Failed to register ESM hook', error);
-      }
-    }
-  } else {
-    consoleSandbox(() => {
-      // eslint-disable-next-line no-console
-      console.warn(
-        `[Sentry] You are using Node.js v${process.versions.node} in ESM mode ("import syntax"). The Sentry Node.js SDK is not compatible with ESM in Node.js versions before 18.19.0 or before 20.6.0. Please either build your application with CommonJS ("require() syntax"), or upgrade your Node.js version.`,
-      );
-    });
-  }
-}
-
 interface NodePreloadOptions {
   debug?: boolean;
   integrations?: string[];
@@ -80,9 +50,7 @@ export function preloadOpenTelemetry(options: NodePreloadOptions = {}): void {
     coreDebug.enable();
   }
 
-  if (!isCjs()) {
-    maybeInitializeEsmLoader();
-  }
+  initializeEsmLoader();
 
   // These are all integrations that we need to pre-load to ensure they are set up before any other code runs
   getPreloadMethods(options.integrations).forEach(fn => {