Add content script noScriptStartedPostMessage option.

The deprecated `window.postMessage` path for the `wxt:content-script-started` message causes bad interactions with sites that have a poorly implemented event listener.

This PR adds an option to exclude the `window.postMessage` event entirely, until such time as WXT completely removes it, which is a breaking change.

Related PRs
#1938
#2035

Author: jviney

packages/wxt/src/types.ts

@@ -713,6 +713,22 @@ export interface BaseContentScriptEntrypointOptions extends BaseScriptEntrypoint
    * @default 'manifest'
    */
   registration?: PerBrowserOption<'manifest' | 'runtime'>;
+  /**
+   * Do not send the `wxt:content-script-started` message via
+   * `window.postMessage`.
+   *
+   * This has been replaced with custom events. The `postMessage` call is kept
+   * for backwards compatibility. For some websites the `postMessage` call is
+   * undesirable, such as those with poorly written message event listeners.
+   *
+   * Setting this to `true` opts into the behaviour that will become the default
+   * in a future version of WXT, where the `postMessage` call is removed
+   * entirely.
+   *
+   * See https://github.com/wxt-dev/wxt/pull/1938 and
+   * https://github.com/wxt-dev/wxt/pull/2035 for a detailed discussion.
+   */
+  noScriptStartedPostMessage?: boolean;
 }
 
 export interface MainWorldContentScriptEntrypointOptions extends BaseContentScriptEntrypointOptions {

packages/wxt/src/utils/__tests__/content-script-context.test.ts

@@ -84,6 +84,22 @@ describe('Content Script Context', () => {
     expect(ctx.isValid).toBe(true);
   });
 
+  describe('noScriptStartedPostMessage', () => {
+    it('should send window.postMessage by default', async () => {
+      const postMessageSpy = vi.spyOn(window, 'postMessage');
+      new ContentScriptContext('test');
+      expect(postMessageSpy).toHaveBeenCalledOnce();
+      postMessageSpy.mockRestore();
+    });
+
+    it('should not send window.postMessage when noScriptStartedPostMessage is true', async () => {
+      const postMessageSpy = vi.spyOn(window, 'postMessage');
+      new ContentScriptContext('test', { noScriptStartedPostMessage: true });
+      expect(postMessageSpy).not.toHaveBeenCalled();
+      postMessageSpy.mockRestore();
+    });
+  });
+
   describe('addEventListener', () => {
     const context = new ContentScriptContext('test');
     it('should infer types correctly for the window target', () => {

packages/wxt/src/utils/content-script-context.ts

@@ -258,16 +258,18 @@ export class ContentScriptContext implements AbortController {
       }),
     );
 
-    // Send message using `window.postMessage` for backwards compatibility to invalidate old versions before WXT changed to `document.dispatchEvent`
-    // TODO: Remove this once WXT version using `document.dispatchEvent` has been released for a while
-    window.postMessage(
-      {
-        type: ContentScriptContext.SCRIPT_STARTED_MESSAGE_TYPE,
-        contentScriptName: this.contentScriptName,
-        messageId: this.id,
-      },
-      '*',
-    );
+    if (!this.options?.noScriptStartedPostMessage) {
+      // Send message using `window.postMessage` for backwards compatibility to invalidate old versions before WXT changed to `document.dispatchEvent`
+      // TODO: Remove this once WXT version using `document.dispatchEvent` has been released for a while
+      window.postMessage(
+        {
+          type: ContentScriptContext.SCRIPT_STARTED_MESSAGE_TYPE,
+          contentScriptName: this.contentScriptName,
+          messageId: this.id,
+        },
+        '*',
+      );
+    }
   }
 
   verifyScriptStartedEvent(event: CustomEvent) {