feat: Support returning values from scripts executed with the scripting API

package.json

@@ -45,16 +45,11 @@
     "*": "prettier --ignore-unknown --write"
   },
   "changelog": {
-    "excludeAuthors": [
-      "aaronklinker1@gmail.com"
-    ]
+    "excludeAuthors": ["aaronklinker1@gmail.com"]
   },
   "pnpm": {
     "peerDependencyRules": {
-      "ignoreMissing": [
-        "@algolia/client-search",
-        "search-insights"
-      ]
+      "ignoreMissing": ["@algolia/client-search", "search-insights"]
     }
   }
 }

packages/wxt/e2e/tests/output-structure.test.ts

@@ -362,11 +362,13 @@ describe('Output Directory Structure', () => {
           function logHello(name) {
             console.log(\`Hello \${name}!\`);
           }
+          _background;
           const definition = defineBackground({
             main() {
               logHello("background");
             }
           });
+          _background;
           chrome;
           function print(method, ...args) {
             return;
@@ -389,6 +391,7 @@ describe('Output Directory Structure', () => {
             throw err;
           }
         })();
+        _background;
         "
       `);
   });

packages/wxt/src/core/builders/vite/index.ts

@@ -19,6 +19,7 @@ import {
 } from '~/core/utils/virtual-modules';
 import { Hookable } from 'hookable';
 import { toArray } from '~/core/utils/arrays';
+import { safeVarName } from '~/core/utils/strings';
 
 export async function createViteBuilder(
   wxtConfig: ResolvedConfig,
@@ -87,14 +88,22 @@ export async function createViteBuilder(
       plugins.push(wxtPlugins.cssEntrypoints(entrypoint, wxtConfig));
     }
 
+    const iifeReturnValueName = safeVarName(entrypoint.name);
     const libMode: vite.UserConfig = {
       mode: wxtConfig.mode,
       plugins,
+      esbuild: {
+        // Add a footer with the returned value so it can return values to `scripting.executeScript`
+        // Footer is added apart of esbuild to make sure it's not minified. It
+        // get's removed if added to `build.rollupOptions.output.footer`
+        // See https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/scripting/executeScript#return_value
+        footer: iifeReturnValueName + ';',
+      },
       build: {
         lib: {
           entry,
           formats: ['iife'],
-          name: '_',
+          name: iifeReturnValueName,
           fileName: entrypoint.name,
         },
         rollupOptions: {

packages/wxt/src/core/utils/__tests__/strings.test.ts

@@ -2,7 +2,8 @@ import { describe, expect, it } from 'vitest';
 import {
   kebabCaseAlphanumeric,
   removeImportStatements,
-} from '~/core/utils/strings';
+  safeVarName,
+} from '../strings';
 
 describe('String utils', () => {
   describe('kebabCaseAlphanumeric', () => {
@@ -18,6 +19,23 @@ describe('String utils', () => {
     });
   });
 
+  describe('safeVarName', () => {
+    it.each([
+      ['Hello world!', '_hello_world'],
+      ['123', '_123'],
+      ['abc-123', '_abc_123'],
+      ['', '_'],
+      [' ', '_'],
+      ['_', '_'],
+    ])(
+      "should convert '%s' to '%s', which can be used for a variable name",
+      (input, expected) => {
+        const actual = safeVarName(input);
+        expect(actual).toBe(expected);
+      },
+    );
+  });
+
   describe('removeImportStatements', () => {
     it('should remove all import formats', () => {
       const imports = `
@@ -30,7 +48,7 @@ import{ registerGithubService, createGithubApi }from "@/utils/github";
 import GitHub from "@/utils/github";
 import "@/utils/github";
 import '@/utils/github';
-import"@/utils/github" 
+import"@/utils/github"
  import'@/utils/github';
     `;
       expect(removeImportStatements(imports).trim()).toEqual('');

packages/wxt/src/core/utils/strings.ts

@@ -5,6 +5,14 @@ export function kebabCaseAlphanumeric(str: string): string {
     .replace(/\s+/g, '-'); // Replace spaces with hyphens
 }
 
+/**
+ * Return a safe variable name for a given string.
+ */
+export function safeVarName(str: string): string {
+  // _ prefix to ensure it doesn't start with a number
+  return '_' + kebabCaseAlphanumeric(str.trim()).replace('-', '_');
+}
+
 /**
  * Removes import statements from the top of a file. Keeps import.meta and inline, async `import()`
  * calls.

packages/wxt/src/types/index.ts

@@ -737,16 +737,24 @@ export interface IsolatedWorldContentScriptDefinition
   extends IsolatedWorldContentScriptEntrypointOptions {
   /**
    * Main function executed when the content script is loaded.
+   *
+   * When running a content script with `browser.scripting.executeScript`,
+   * values returned from this function will be returned in the `executeScript`
+   * result as well. Otherwise returning a value does nothing.
    */
-  main(ctx: ContentScriptContext): void | Promise<void>;
+  main(ctx: ContentScriptContext): any | Promise<any>;
 }
 
 export interface MainWorldContentScriptDefinition
   extends MainWorldContentScriptEntrypointOptions {
   /**
    * Main function executed when the content script is loaded.
+   *
+   * When running a content script with `browser.scripting.executeScript`,
+   * values returned from this function will be returned in the `executeScript`
+   * result as well. Otherwise returning a value does nothing.
    */
-  main(): void | Promise<void>;
+  main(): any | Promise<any>;
 }
 
 export type ContentScriptDefinition =
@@ -763,8 +771,12 @@ export interface BackgroundDefinition extends BackgroundEntrypointOptions {
 export interface UnlistedScriptDefinition extends BaseEntrypointOptions {
   /**
    * Main function executed when the unlisted script is ran.
+   *
+   * When running a content script with `browser.scripting.executeScript`,
+   * values returned from this function will be returned in the `executeScript`
+   * result as well. Otherwise returning a value does nothing.
    */
-  main(): void | Promise<void>;
+  main(): any | Promise<any>;
 }
 
 /**

packages/wxt/src/virtual/content-script-isolated-world-entrypoint.ts

@@ -2,16 +2,23 @@
 import { logger } from '../sandbox/utils/logger';
 import { ContentScriptContext } from 'wxt/client';
 
-(async () => {
+const result = (async () => {
   try {
     const { main, ...options } = definition;
     const ctx = new ContentScriptContext(import.meta.env.ENTRYPOINT, options);
 
-    await main(ctx);
+    return await main(ctx);
   } catch (err) {
     logger.error(
       `The content script "${import.meta.env.ENTRYPOINT}" crashed on startup!`,
       err,
     );
+    throw err;
   }
 })();
+
+// Return the main function's result to the background when executed via the
+// scripting API. Default export causes the IIFE to return a value.
+// https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/scripting/executeScript#return_value
+// Tested on both Chrome and Firefox
+export default result;

packages/wxt/src/virtual/content-script-main-world-entrypoint.ts

@@ -1,14 +1,21 @@
 import definition from 'virtual:user-content-script-main-world-entrypoint';
 import { logger } from '../sandbox/utils/logger';
 
-(async () => {
+const result = (async () => {
   try {
     const { main } = definition;
-    await main();
+    return await main();
   } catch (err) {
     logger.error(
       `The content script "${import.meta.env.ENTRYPOINT}" crashed on startup!`,
       err,
     );
+    throw err;
   }
 })();
+
+// Return the main function's result to the background when executed via the
+// scripting API. Default export causes the IIFE to return a value.
+// https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/scripting/executeScript#return_value
+// Tested on both Chrome and Firefox
+export default result;

packages/wxt/src/virtual/unlisted-script-entrypoint.ts

@@ -1,13 +1,20 @@
 import definition from 'virtual:user-unlisted-script-entrypoint';
 import { logger } from '../sandbox/utils/logger';
 
-(async () => {
+const result = (async () => {
   try {
-    await definition.main();
+    return await definition.main();
   } catch (err) {
     logger.error(
       `The unlisted script "${import.meta.env.ENTRYPOINT}" crashed on startup!`,
       err,
     );
+    throw err;
   }
 })();
+
+// Return the main function's result to the background when executed via the
+// scripting API. Default export causes the IIFE to return a value.
+// https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/scripting/executeScript#return_value
+// Tested on both Chrome and Firefox
+export default result;