feat: Add content script noScriptStartedPostMessage option (#2265)

Co-authored-by: Aaron <aaronklinker1@gmail.com>

Author: jviney

packages/wxt/src/types.ts

@@ -711,6 +711,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 behavior 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) {