From cfb384e618e13622783189441aa4fae0cef5c178 Mon Sep 17 00:00:00 2001
From: Shubhrajit Sadhukhan <champa.281982@gmail.com>
Date: Tue, 12 May 2026 17:38:38 +0530
Subject: [PATCH] feat: Add warning for missing Firefox extension ID in
 manifest (#2293)

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Patryk Kuniczak <p.kuniczak@gmail.com>
Co-authored-by: Aaron <aaronklinker1@gmail.com>
---
 .../wxt/src/core/utils/__tests__/manifest.test.ts     |  2 --
 packages/wxt/src/core/utils/manifest.ts               | 11 +++++++++++
 packages/wxt/src/types.ts                             | 10 +++++++++-
 3 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/packages/wxt/src/core/utils/__tests__/manifest.test.ts b/packages/wxt/src/core/utils/__tests__/manifest.test.ts
index 42199c82..eb32d22e 100644
--- a/packages/wxt/src/core/utils/__tests__/manifest.test.ts
+++ b/packages/wxt/src/core/utils/__tests__/manifest.test.ts
@@ -1693,7 +1693,6 @@ describe('Manifest Utils', () => {
 
         expect(actual.version).toBe('0.0.0');
         expect(actual.version_name).toBeUndefined();
-        expect(wxt.logger.warn).toBeCalledTimes(1);
         expect(wxt.logger.warn).toBeCalledWith(
           expect.stringContaining('Extension version not found'),
         );
@@ -2125,7 +2124,6 @@ describe('Manifest Utils', () => {
         const { manifest } = await generateManifest([], buildOutput);
 
         expect(manifest.manifest_version).toBe(expectedVersion);
-        expect(wxt.logger.warn).toBeCalledTimes(1);
         expect(wxt.logger.warn).toBeCalledWith(
           expect.stringContaining(
             '`manifest.manifest_version` config was set, but ignored',
diff --git a/packages/wxt/src/core/utils/manifest.ts b/packages/wxt/src/core/utils/manifest.ts
index 6bcfaa15..471cfd70 100644
--- a/packages/wxt/src/core/utils/manifest.ts
+++ b/packages/wxt/src/core/utils/manifest.ts
@@ -129,6 +129,17 @@ export async function generateManifest(
     );
   }
 
+  if (
+    wxt.config.browser === 'firefox' &&
+    !manifest.browser_specific_settings?.gecko?.id &&
+    !wxt.config.suppressWarnings?.firefoxId
+  ) {
+    wxt.logger.warn(
+      'Firefox requires extension ID for MV3 and recommends it for MV2.\n' +
+        'For more details, see: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings#id',
+    );
+  }
+
   addEntrypoints(manifest, entrypoints, buildOutput);
 
   if (wxt.config.browser === 'firefox') {
diff --git a/packages/wxt/src/types.ts b/packages/wxt/src/types.ts
index cec8349f..7998ec28 100644
--- a/packages/wxt/src/types.ts
+++ b/packages/wxt/src/types.ts
@@ -159,6 +159,11 @@ export interface InlineConfig {
      * https://extensionworkshop.com/documentation/develop/firefox-builtin-data-consent
      */
     firefoxDataCollection?: boolean;
+    /**
+     * Suppress warnings when the Firefox extension ID is missing.
+     * https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings#id
+     */
+    firefoxId?: boolean;
   };
   /**
    * Configure browser startup. Options set here can be overridden in a
@@ -1530,7 +1535,10 @@ export interface ResolvedConfig {
   alias: Record<string, string>;
   experimental: {};
   /** List of warning identifiers to suppress during the build process. */
-  suppressWarnings: { firefoxDataCollection?: boolean };
+  suppressWarnings: {
+    firefoxDataCollection?: boolean;
+    firefoxId?: boolean;
+  };
   dev: {
     /** Only defined during dev command */
     server?: {