From a6bcebb998b7006b8acc467f8996c83deea7a88e Mon Sep 17 00:00:00 2001
From: Tim Fish <tim@timfish.uk>
Date: Mon, 15 Jul 2024 12:55:41 +0200
Subject: [PATCH 1/2] docs(node): Update Node `README.md`

---
 packages/node/README.md | 37 +++++++++++++++++++++++++++----------
 1 file changed, 27 insertions(+), 10 deletions(-)

diff --git a/packages/node/README.md b/packages/node/README.md
index 20fe8cc175c3..e1c605c2789c 100644
--- a/packages/node/README.md
+++ b/packages/node/README.md
@@ -21,6 +21,11 @@ yarn add @sentry/node
 
 ## Usage
 
+Sentry should be initialized as early in your app as possible. It is essential that you call `Sentry.init` before you
+require any other modules in your application, otherwise auto-instrumentation of these modules will **not** work.
+
+You need to create a file named `instrument.js` that imports and initializes Sentry:
+
 ```js
 // CJS Syntax
 const Sentry = require('@sentry/node');
@@ -32,27 +37,39 @@ Sentry.init({
   // ...
 });
 ```
+You need to require or import the `instrument.js` file before importing any other modules in your application. This is
+necessary to ensure that Sentry can automatically instrument all modules in your application:
 
-Note that it is necessary to initialize Sentry **before you import any package that may be instrumented by us**.
+```js
+// Import this first!
+import "./instrument";
 
-[More information on how to set up Sentry for Node in v8.](https://github.com/getsentry/sentry-javascript/blob/develop/docs/v8-node.md)
+// Now import other modules
+import http from "http";
+
+// Your application code goes here
+```
 
 ### ESM Support
 
-Due to the way OpenTelemetry handles instrumentation, this only works out of the box for CommonJS (`require`)
-applications.
+When running your application in ESM mode, you should use the Node.js
+[`--import`](https://nodejs.org/api/cli.html#--importmodule) command line option to ensure that Sentry is loaded before
+the application code is evaluated.
 
-There is experimental support for running OpenTelemetry with ESM (`"type": "module"`):
+Adjust the Node.js call for your application to use the `--import` parameter and point it at `instrument.js`, which
+contains your `Sentry.init`() code:
 
 ```bash
-node --experimental-loader=@opentelemetry/instrumentation/hook.mjs ./app.js
+# Note: This is only available for Node v18.19.0 onwards.
+node --import ./instrument.mjs app.mjs
 ```
 
-You'll need to install `@opentelemetry/instrumentation` in your app to ensure this works.
+If it is not possible for you to pass the `--import` flag to the Node.js binary, you can alternatively use the
+`NODE_OPTIONS` environment variable as follows:
 
-See
-[OpenTelemetry Instrumentation Docs](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation#instrumentation-for-es-modules-in-nodejs-experimental)
-for details on this - but note that this is a) experimental, and b) does not work with all integrations.
+```bash
+NODE_OPTIONS="--import ./instrument.mjs" npm run start
+```
 
 ## Links
 

From b10d9fcbb76a6d8135b4c9a963d205e0b79c0da9 Mon Sep 17 00:00:00 2001
From: Tim Fish <tim@timfish.uk>
Date: Mon, 15 Jul 2024 13:01:29 +0200
Subject: [PATCH 2/2] lint

---
 packages/node/README.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/node/README.md b/packages/node/README.md
index e1c605c2789c..6471538fb4f0 100644
--- a/packages/node/README.md
+++ b/packages/node/README.md
@@ -37,15 +37,16 @@ Sentry.init({
   // ...
 });
 ```
+
 You need to require or import the `instrument.js` file before importing any other modules in your application. This is
 necessary to ensure that Sentry can automatically instrument all modules in your application:
 
 ```js
 // Import this first!
-import "./instrument";
+import './instrument';
 
 // Now import other modules
-import http from "http";
+import http from 'http';
 
 // Your application code goes here
 ```