ref(docs): Update migration guide to use --require/--import flag (#11970)

Co-authored-by: Luca Forstner <[email protected]>

Author: andreiborza

MIGRATION.md

@@ -20,9 +20,9 @@ stable release of `8.x` comes out).
 
 ## 1. Version Support changes:
 
-**Node.js**: We now official support Node 14.18+ for our CJS package, and Node 18.8+ for our ESM package. This applies
-to `@sentry/node` and all of our node-based server-side sdks (`@sentry/nextjs`, `@sentry/serverless`, etc.). We no
-longer test against Node 8, 10, or 12 and cannot guarantee that the SDK will work as expected on these versions.
+**Node.js**: We now officially support Node 14.18+ for our CJS package, and Node 18.19.1+ for our ESM package. This
+applies to `@sentry/node` and all of our node-based server-side sdks (`@sentry/nextjs`, `@sentry/serverless`, etc.). We
+no longer test against Node 8, 10, or 12 and cannot guarantee that the SDK will work as expected on these versions.
 
 **Browser**: Our browser SDKs (`@sentry/browser`, `@sentry/react`, `@sentry/vue`, etc.) now require ES2018+ compatible
 browsers. This means that we no longer support IE11 (end of an era). This also means that the Browser SDK requires the

docs/v8-initializing.md

@@ -21,7 +21,7 @@ In an environment with multiple execution contexts (e.g. Node), you can setup mu
 different contexts, like this:
 
 ```js
-import * as Sentry from '@sentry/browser';
+import * as Sentry from '@sentry/node';
 
 // Sets up the _default_ client
 Sentry.init({

docs/v8-node.md

@@ -16,7 +16,8 @@ We support the following Node Frameworks out of the box:
 
 - [Express](#express)
 - [Fastify](#fastify)
-- Koa
+- [Connect](#connect)
+- [Koa](#koa)
 - Nest.js
 - Hapi
 
@@ -52,13 +53,36 @@ Sentry.init({
 const app = express();
 ```
 
+We recommend creating a file named `instrument.js` that imports and initializes Sentry.
+
 ```js
-// In v8, in order to ensure express is instrumented,
-// you have to initialize before you import:
+// In v8, create a separate file that initializes sentry.
+// Then pass the file to Node via --require or --import.
 const Sentry = require('@sentry/node');
 Sentry.init({
   // ...
 });
+```
+
+Adjust the Node.js call for your application to use the [--require](https://nodejs.org/api/cli.html#-r---require-module)
+or [--import](https://nodejs.org/api/cli.html#--importmodule) parameter and point it at `instrument.js`. Using
+`--require` or `--import` is the easiest way to guarantee that Sentry is imported and initialized before any other
+modules in your application
+
+```bash
+# If you are using CommonJS (CJS)
+node --require ./instrument.js app.js
+
+# If you are using ECMAScript Modules (ESM)
+# Note: This is only available for Node v18.19.0 onwards.
+node --import ./instrument.mjs app.mjs
+```
+
+**Alternatively**, if you cannot run node with `--require` or `--import`, add a top level import of `instrument.js` in
+your application.
+
+```js
+require('./instrument.js');
 
 const express = require('express');
 const app = express();
@@ -75,8 +99,11 @@ See [New Performance APIs](./v8-new-performance-apis.md) for details.
 
 ### ESM Support
 
-For now, ESM support is only experimental. For the time being we only fully support CJS-based Node application - we are
-working on this during the v8 alpha/beta cycle.
+Instrumentation works out of the box for CommonJS (CJS) applications based on require() calls. This means that as long
+as your application is either natively in CJS, or compiled at build time to CJS, everything will work without any
+further setup.
+
+ECMAScript Modules (ESM) are only supported for Node v18.19.0 onwards.
 
 ### Using Custom OpenTelemetry Instrumentation
 
@@ -153,12 +180,6 @@ your Express app.
 
 ```js
 const Sentry = require('@sentry/node');
-
-Sentry.init({
-  dsn: '__DSN__',
-  tracesSampleRate: 1,
-});
-
 const express = require('express');
 const app = express();
 
@@ -177,12 +198,6 @@ your Fastify app.
 
 ```js
 const Sentry = require('@sentry/node');
-
-Sentry.init({
-  dsn: '__DSN__',
-  tracesSampleRate: 1,
-});
-
 const { fastify } = require('fastify');
 const app = fastify();
 Sentry.setupFastifyErrorHandler(app);
@@ -191,3 +206,40 @@ Sentry.setupFastifyErrorHandler(app);
 
 app.listen();
 ```
+
+## Connect
+
+The following shows how you can setup Connect instrumentation in v8. This will capture performance data & errors for
+your Fastify app.
+
+```js
+const connect = require('connect');
+const Sentry = require('@sentry/node');
+const app = connect();
+
+Sentry.setupConnectErrorHandler(app);
+
+// Add your routes, etc.
+
+app.listen(3030);
+```
+
+## Koa
+
+The following shows how you can setup Koa instrumentation in v8. This will capture performance data & errors for your
+Fastify app.
+
+```js
+const Koa = require('koa');
+const Router = require('@koa/router');
+const Sentry = require('@sentry/node');
+
+const router = new Router();
+const app = new Koa();
+
+Sentry.setupKoaErrorHandler(app);
+
+// Add your routes, etc.
+
+app.listen(3030);
+```