From 0e7ad051c8d9b64a4f6465cf014a84c661586dcb Mon Sep 17 00:00:00 2001
From: Abhijeet Prasad <aprasad@sentry.io>
Date: Wed, 30 Oct 2024 16:46:43 -0400
Subject: [PATCH] feat(js): Update esm warning for local variables

---
 .../integrations/localvariables.mdx              | 16 ++++++++++++++++
 .../javascript/common/configuration/options.mdx  | 11 ++---------
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx b/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx
index a2f5618cf1a69..f73adc55a47f8 100644
--- a/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx
+++ b/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx
@@ -44,6 +44,22 @@ Sentry.init({
 
 The local variables integration only captures local variables from application code (`in_app = true`). Frames of a stacktrace originating from `node_modules` will not have local variables attached to them.
 
+<Alert level="warning" title="Issues with ESM">
+
+Due to an [open Node.js issue](https://github.com/nodejs/node/issues/38439), we are currently unable to capture local variables for unhandled errors when using JavaScript modules (ESM).
+
+To work around this, wrap relevant code in a try-catch block and call `captureException` with the error so that Sentry can capture local variables.
+
+```javascript
+try {
+  // Your code here
+} catch (error) {
+  Sentry.captureException(error);
+}
+```
+
+</Alert>
+
 <Alert level="warning" title="Minified Variables">
 
 Minified local variable names attached to exception frames can't be unminified by Sentry at this time. There's an [active proposal](https://github.com/tc39/source-map/blob/main/proposals/scopes.md) for the sourcemaps spec that will add this capability.
diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx
index da76c18488cef..a9dc026df4c34 100644
--- a/docs/platforms/javascript/common/configuration/options.mdx
+++ b/docs/platforms/javascript/common/configuration/options.mdx
@@ -245,16 +245,9 @@ Set this boolean to `false` to disable sending of client reports. Client reports
 <PlatformCategorySection supported={['server', 'serverless']}>
 <ConfigKey name="include-local-variables">
 
-Set this boolean to `true` to add stack local variables to stack traces.
+Set this boolean to `true` to add stack local variables to stack traces. Defaults to `false`.
 
-<Alert level="warning">
-
-Due to an [open Node.js issue](https://github.com/nodejs/node/issues/38439), we are currently unable to capture local variables for unhandled errors when using
-JavaScript modules (ESM).
-
-See the <PlatformLink to="/configuration/integrations/localvariables">integration options</PlatformLink> for a workaround.
-
-</Alert>
+For more advanced configuration options, see the documentation on the <PlatformLink to="/configuration/integrations/localvariables">Local Variables integration options</PlatformLink>.
 
 </ConfigKey>
 </PlatformCategorySection>