From 98e6826ee30b55544a3d03664d448583852344d6 Mon Sep 17 00:00:00 2001
From: Dario Piotrowicz <dario@cloudflare.com>
Date: Wed, 30 Apr 2025 10:28:03 +0100
Subject: [PATCH 1/2] add `keep_names` how-to page

---
 pages/cloudflare/howtos/_meta.json     |  3 +-
 pages/cloudflare/howtos/keep_names.mdx | 38 ++++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 pages/cloudflare/howtos/keep_names.mdx

diff --git a/pages/cloudflare/howtos/_meta.json b/pages/cloudflare/howtos/_meta.json
index 79facd0..2c781b5 100644
--- a/pages/cloudflare/howtos/_meta.json
+++ b/pages/cloudflare/howtos/_meta.json
@@ -4,5 +4,6 @@
   "dev-deploy": "Develop and Deploy",
   "env-vars": "Environment Variables",
   "image": "Image Optimization",
-  "custom-worker": "Custom Worker"
+  "custom-worker": "Custom Worker",
+  "keep_names": "__name issues"
 }
diff --git a/pages/cloudflare/howtos/keep_names.mdx b/pages/cloudflare/howtos/keep_names.mdx
new file mode 100644
index 0000000..3c94d08
--- /dev/null
+++ b/pages/cloudflare/howtos/keep_names.mdx
@@ -0,0 +1,38 @@
+import { Callout } from "nextra/components";
+
+## `__name` issues
+
+When using the OpenNext adapter, Wrangler processes the worker's code with [esbuild](https://esbuild.github.io/), and by default
+enables the [`keep-names`](https://esbuild.github.io/api/#keep-names) option. While this is generally useful for debugging, it can
+cause issues with certain Next.js libraries (e.g. [next-themes](https://www.npmjs.com/package/next-themes)) that convert scripts
+to strings. This happens because `esbuild` introduces an `__name` function at the top of modules, which may inadvertently appear
+in the generated script strings. When these strings are evaluated at runtime, the `__name` function might therefore not be defined,
+leading to errors like the following:
+
+```
+Uncaught ReferenceError: __name is not defined
+```
+
+<Callout>
+  Note that depending on your minification settings, the `__name` identifier might be minified, making the
+  error message less clear and potentially not explicitly mentioning `__name` in such cases.
+</Callout>
+
+### How to fix such issues
+
+To fix the issue you can simply set the `keep_names` option to `false` in your `wrangler.jsonc` file, like in the following example:
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "main": ".open-next/worker.js",
+  "name": "my-app",
+  "keep_names": false,
+  /* ... */
+}
+```
+
+One potential drawback of this solution is that, depending on your minification settings, you may lose the ability to view the original
+function names in debugging tools.
+
+<Callout>You must use Wrangler version `4.13.0` or later to use this option.</Callout>

From 6021a403311e286b61d931afc92fdcd053fb5ba2 Mon Sep 17 00:00:00 2001
From: Dario Piotrowicz <dario.piotrowicz@gmail.com>
Date: Wed, 30 Apr 2025 11:11:01 +0100
Subject: [PATCH 2/2] Apply suggestions from code review

Co-authored-by: Victor Berchet <victor@suumit.com>
---
 pages/cloudflare/howtos/keep_names.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pages/cloudflare/howtos/keep_names.mdx b/pages/cloudflare/howtos/keep_names.mdx
index 3c94d08..acd3014 100644
--- a/pages/cloudflare/howtos/keep_names.mdx
+++ b/pages/cloudflare/howtos/keep_names.mdx
@@ -5,9 +5,9 @@ import { Callout } from "nextra/components";
 When using the OpenNext adapter, Wrangler processes the worker's code with [esbuild](https://esbuild.github.io/), and by default
 enables the [`keep-names`](https://esbuild.github.io/api/#keep-names) option. While this is generally useful for debugging, it can
 cause issues with certain Next.js libraries (e.g. [next-themes](https://www.npmjs.com/package/next-themes)) that convert scripts
-to strings. This happens because `esbuild` introduces an `__name` function at the top of modules, which may inadvertently appear
+to strings. This happens because `esbuild` introduces a `__name` function at the top of modules, which may inadvertently appear
 in the generated script strings. When these strings are evaluated at runtime, the `__name` function might therefore not be defined,
-leading to errors like the following:
+leading to errors logged in the developper console:
 
 ```
 Uncaught ReferenceError: __name is not defined
@@ -20,7 +20,7 @@ Uncaught ReferenceError: __name is not defined
 
 ### How to fix such issues
 
-To fix the issue you can simply set the `keep_names` option to `false` in your `wrangler.jsonc` file, like in the following example:
+To fix the issue you can simply set the `keep_names` option to `false` in your [`wrangler.jsonc` file](https://developers.cloudflare.com/workers/wrangler/configuration), like in the following example:
 
 ```jsonc
 {