Add clarification for otel-js apps written in CJS and ESM (open-telemetry#8666)

Co-authored-by: otelbot <197425009+otelbot@users.noreply.github.com>
Co-authored-by: Vitor Vasconcellos <vitor.vasconcellos@mercadolivre.com>
Co-authored-by: Vitor Vasconcellos <vvasconcellos1@gmail.com>

Author: 3 people

content/en/docs/languages/js/_includes/esm-support-note.md

@@ -0,0 +1,9 @@
+---
+---
+
+> [!NOTE]
+>
+> The OpenTelemetry documentation assumes that the compiled application is run
+> as [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules).
+> If the application runs as ESM, add the loader hook as specified in the
+> [ESM Support Doc](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md).

content/en/docs/languages/js/getting-started/nodejs.md

@@ -245,6 +245,14 @@ Listening for requests on http://localhost:8080
 
 {{% /tab %}} {{< /tabpane >}}
 
+(Note: If your application is written in JavaScript as ECMAScript Modules (ESM),
+or compiled to ESM from TypeScript, then a loader hook is required to properly
+support instrumentation. Use
+`node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --require ./instrumentation.js app.js`.
+See
+[ESM support docs](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md)
+for details on ESM support in OpenTelemetry.)
+
 Open <http://localhost:8080/rolldice> in your web browser and reload the page a
 few times. After a while you should see the spans printed in the console by the
 `ConsoleSpanExporter`.
@@ -553,5 +561,7 @@ diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);
 
 {{% /tab %}} {{< /tabpane >}}
 
+{{% include esm-support-note.md %}}
+
 [traces]: /docs/concepts/signals/traces/
 [metrics]: /docs/concepts/signals/metrics/

content/en/docs/languages/js/instrumentation.md

@@ -31,6 +31,8 @@ about manual instrumentation.
 You don't have to use the example app: if you want to instrument your own app or
 library, follow the instructions here to adapt the process to your own code.
 
+{{% include esm-support-note.md %}}
+
 ### Dependencies {#example-app-dependencies}
 
 Create an empty NPM `package.json` file in a new directory:

content/en/docs/languages/js/libraries.md

@@ -19,6 +19,8 @@ For example,
 will automatically create [spans](/docs/concepts/signals/traces/#spans) based on
 the inbound HTTP requests.
 
+{{% include esm-support-note.md %}}
+
 ### Setup
 
 Each instrumentation library is an NPM package. For example, here’s how you can

content/en/docs/languages/js/propagation.md

@@ -7,6 +7,8 @@ cSpell:ignore: rolldice
 
 {{% docs/languages/propagation %}}
 
+{{% include esm-support-note.md %}}
+
 ## Automatic context propagation
 
 [Instrumentation libraries](../libraries/) like

content/en/docs/languages/js/resources.md

@@ -16,6 +16,8 @@ Follow the instructions in the [Getting Started - Node.js][], so that you have
 the files `package.json`, `app.js` (or `app.ts`) and `instrumentation.mjs` (or
 `instrumentation.ts`).
 
+{{% include esm-support-note.md %}}
+
 ## Process & Environment Resource Detection
 
 Out of the box, the Node.js SDK detects [process and process runtime

content/en/docs/languages/js/serverless.md

@@ -8,6 +8,11 @@ cSpell:ignore: otelwrapper
 This guide shows how to get started with tracing serverless functions using
 OpenTelemetry instrumentation libraries.
 
+> [!NOTE]
+>
+> The OpenTelemetry documentation assume that the compiled application is run as
+> [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules).
+
 ## AWS Lambda
 
 > [!NOTE]

static/refcache.json

@@ -12627,6 +12627,10 @@
     "StatusCode": 206,
     "LastSeen": "2026-03-02T09:52:36.24661858Z"
   },
+  "https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md": {
+    "StatusCode": 206,
+    "LastSeen": "2026-03-17T09:57:57.21652344Z"
+  },
   "https://github.com/open-telemetry/opentelemetry-js/discussions": {
     "StatusCode": 206,
     "LastSeen": "2026-02-28T09:44:10.519724831Z"
@@ -18823,6 +18827,10 @@
     "StatusCode": 206,
     "LastSeen": "2026-03-02T09:58:08.183553018Z"
   },
+  "https://nodejs.org/api/modules.html#modules-commonjs-modules": {
+    "StatusCode": 206,
+    "LastSeen": "2025-12-18T11:01:15.225540416Z"
+  },
   "https://nodejs.org/api/perf_hooks.html": {
     "StatusCode": 206,
     "LastSeen": "2026-03-02T09:58:30.616931835Z"