feat: Remove support for initialising via --require (#22513)

Author: timfish

MIGRATION.md

@@ -97,6 +97,24 @@ Affected SDKs: `@sentry/node` and all dependents.
 
 The new channel-based instrumentations (using `orchestrion` instead of `import-in-the-middle`) are now the default. They were available opt-in in v10. This unlocks instrumenting at run and build time, which enables instrumentation at deployment targets like Vercel and Netlify, as well as using instrumentations on non-Node runtimes like Cloudflare, Bun and Deno. For most users this requires no changes.
 
+### Initializing via `--require` is no longer supported
+
+Affected SDKs: `@sentry/node` and all dependents.
+
+Node re-runs `--require` preloads on the internal module loader thread it spawns for `Module.register()` — which the SDK triggers itself when it installs its instrumentation hooks. A `--require`d instrument file therefore ran `Sentry.init()` a second time, on a thread that never executes any of your code. The SDK now skips initialization on that thread and warns when it detects that it was loaded through `--require`.
+
+Use [`--import`](https://nodejs.org/api/cli.html#--importmodule) instead. It is not re-run on the loader thread, and it works for CommonJS apps too — the instrument file's extension (`.cjs`, or `.js` in a package without `"type": "module"`) is what decides that it loads as CommonJS:
+
+```bash
+# Before
+node --require ./instrument.js app.js
+
+# After
+node --import ./instrument.js app.js
+```
+
+The same applies to the no-code entry points, e.g. `node --import=@sentry/node/init app.js` and `node --import @sentry/node/preload app.js`.
+
 ### Span streaming is now the default
 
 Affected SDKs: All SDKs.

dev-packages/e2e-tests/test-applications/create-remix-app-v2-non-vite/package.json

@@ -4,7 +4,7 @@
   "scripts": {
     "build": "remix build",
     "dev": "remix dev",
-    "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/index.js",
+    "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/index.js",
     "typecheck": "tsc",
     "clean": "npx rimraf node_modules pnpm-lock.yaml",
     "test:build": "pnpm install && npx playwright install && pnpm build",

dev-packages/e2e-tests/test-applications/create-remix-app-v2/package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "build": "remix vite:build && pnpm typecheck",
     "dev": "remix vite:dev",
-    "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
+    "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
     "typecheck": "tsc",
     "clean": "npx rimraf node_modules pnpm-lock.yaml",
     "test:build": "pnpm install && pnpm build",

dev-packages/e2e-tests/test-applications/create-remix-app-v2/tests/build-injection.test.ts

@@ -4,7 +4,7 @@ import { expect, test } from '@playwright/test';
 
 // The `db.test.ts` runtime assertions prove orchestrion spans appear, but spans alone
 // don't prove they came from the BUILD-time transform: if the Vite plugin silently
-// failed to load, the deps would stay external and the runtime `--require` hook would
+// failed to load, the deps would stay external and the runtime `--import` hook would
 // inject the channels at runtime instead - the span tests would still pass. These
 // assertions inspect the built server bundle directly so a broken plugin can't hide
 // behind that runtime fallback. Only relevant in the orchestrion variant.

dev-packages/e2e-tests/test-applications/node-express-cjs-preload/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "scripts": {
-    "start": "node --require @sentry/node/preload src/app.js",
+    "start": "node --import @sentry/node/preload src/app.js",
     "clean": "npx rimraf node_modules pnpm-lock.yaml",
     "test:build": "pnpm install",
     "test:assert": "playwright test"

dev-packages/e2e-tests/test-applications/remix-server-timing/package.json

@@ -4,7 +4,7 @@
   "scripts": {
     "build": "remix vite:build && pnpm typecheck",
     "dev": "remix vite:dev",
-    "start": "NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build/server/index.js",
+    "start": "NODE_OPTIONS='--import=./instrument.server.cjs' remix-serve build/server/index.js",
     "typecheck": "tsc",
     "clean": "npx rimraf node_modules pnpm-lock.yaml",
     "test:build": "pnpm install && pnpm build",

dev-packages/node-integration-tests/suites/no-code/app.js

@@ -17,15 +17,6 @@ describe('no-code init', () => {
     cleanupChildProcesses();
   });
 
-  test('CJS', async () => {
-    await createRunner(__dirname, 'app.js')
-      .withFlags('--require=@sentry/node/init')
-      .withMockSentryServer()
-      .expect({ event: EVENT })
-      .start()
-      .completed();
-  });
-
   describe('--import', () => {
     test('ESM', async () => {
       await createRunner(__dirname, 'app.mjs')

dev-packages/node-integration-tests/suites/no-code/test.ts

@@ -91,11 +91,11 @@ module.exports = { out_of_app_function };`,
       .completed();
   });
 
-  test('Should include local variables when instrumenting via --require', async () => {
-    const requirePath = path.resolve(__dirname, 'local-variables-instrument.js');
+  test('Should include local variables when instrumenting via --import', async () => {
+    const instrumentPath = path.resolve(__dirname, 'local-variables-instrument.cjs');
 
     await createRunner(__dirname, 'local-variables-no-sentry.js')
-      .withFlags(`--require=${requirePath}`)
+      .withFlags(`--import=${instrumentPath}`)
       .expect({ event: EXPECTED_LOCAL_VARIABLES_EVENT })
       .start()
       .completed();