From 7dbe18ba0c2ea4636b897e0c9eebf352924a5a59 Mon Sep 17 00:00:00 2001
From: Aaron <aaronklinker1@gmail.com>
Date: Sun, 26 Jul 2026 11:14:50 -0500
Subject: [PATCH] fix!: Update content and unlisted script `globalName` default
 to `false` (#2511)

BREAKING CHANGE: If your script needs to return a value, like for `browser.scripting.executeScript`, set `globalName: true` to maintain the old behavior.
---
 .../wxt/e2e/tests/output-structure.test.ts    | 21 ++++++++++++++++++-
 packages/wxt/src/core/builders/vite/index.ts  |  2 +-
 packages/wxt/src/types.ts                     |  2 +-
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/packages/wxt/e2e/tests/output-structure.test.ts b/packages/wxt/e2e/tests/output-structure.test.ts
index c3c638fa..b18ab995 100644
--- a/packages/wxt/e2e/tests/output-structure.test.ts
+++ b/packages/wxt/e2e/tests/output-structure.test.ts
@@ -506,7 +506,7 @@ describe('Output Directory Structure', () => {
   });
 
   describe('globalName option', () => {
-    it('generates an IIFE with a default name', async () => {
+    it('does not generate a IIFE return variable by default', async () => {
       const project = new TestProject();
       project.addFile(
         'entrypoints/content.js',
@@ -518,6 +518,25 @@ describe('Output Directory Structure', () => {
 
       await project.build({ vite: () => ({ build: { minify: false } }) });
 
+      const output = await project.serializeFile(
+        '.output/chrome-mv3/content-scripts/content.js',
+      );
+      expect(output.includes('var content')).toBe(false);
+    });
+
+    it('does generates the IIFE name based on the entrypoint name when true', async () => {
+      const project = new TestProject();
+      project.addFile(
+        'entrypoints/content.js',
+        `export default defineContentScript({
+          globalName: true,
+          matches: ["*://*/*"],
+          main() {},
+        })`,
+      );
+
+      await project.build({ vite: () => ({ build: { minify: false } }) });
+
       const output = await project.serializeFile(
         '.output/chrome-mv3/content-scripts/content.js',
       );
diff --git a/packages/wxt/src/core/builders/vite/index.ts b/packages/wxt/src/core/builders/vite/index.ts
index f24b9c62..5175d774 100644
--- a/packages/wxt/src/core/builders/vite/index.ts
+++ b/packages/wxt/src/core/builders/vite/index.ts
@@ -145,7 +145,7 @@ export async function createViteBuilder(
         iifeReturnValueName = entrypoint.options.globalName(entrypoint);
       }
 
-      if (entrypoint.options.globalName === false) {
+      if (!entrypoint.options.globalName) {
         plugins.push(wxtPlugins.iifeAnonymous(iifeReturnValueName));
       } else {
         plugins.push(wxtPlugins.iifeFooter(iifeReturnValueName));
diff --git a/packages/wxt/src/types.ts b/packages/wxt/src/types.ts
index 3ad0a3a3..7b3790b0 100644
--- a/packages/wxt/src/types.ts
+++ b/packages/wxt/src/types.ts
@@ -680,7 +680,7 @@ export interface BaseScriptEntrypointOptions extends BaseEntrypointOptions {
    * - `function`: A function that receives the entrypoint and returns a string to
    *   use as the variable name.
    *
-   * @default true
+   * @default false
    */
   globalName?: string | boolean | ((entrypoint: Entrypoint) => string);
 }