feat(experimental): First-class support for excluding webextension-polyfill

packages/wxt-demo/wxt.config.ts

@@ -20,6 +20,7 @@ export default defineConfig({
   },
   experimental: {
     entrypointImporter: 'vite-node',
+    extensionApi: 'chrome',
   },
   runner: {
     startUrls: ['https://duckduckgo.com'],

packages/wxt/build.config.ts

@@ -13,7 +13,7 @@ export default defineBuildConfig([
       {
         builder: 'mkdist',
         input: 'src',
-        pattern: ['**/*', '!**/__tests__', '!**/*.md', '!virtual'],
+        pattern: ['**/*', '!**/__tests__', '!**/*.md', '!virtual', '!@types'],
         declaration: true,
       },
     ],

packages/wxt/e2e/tests/modules.test.ts

@@ -194,7 +194,7 @@ describe('Module Helpers', () => {
       await project.build({
         experimental: {
           // reduce build output when comparing test failures
-          includeBrowserPolyfill: false,
+          extensionApi: 'chrome',
         },
       });
 
@@ -216,7 +216,7 @@ describe('Module Helpers', () => {
       await project.build({
         experimental: {
           // reduce build output when comparing test failures
-          includeBrowserPolyfill: false,
+          extensionApi: 'chrome',
         },
       });
 
@@ -239,7 +239,7 @@ describe('Module Helpers', () => {
       await project.build({
         experimental: {
           // reduce build output when comparing test failures
-          includeBrowserPolyfill: false,
+          extensionApi: 'chrome',
         },
       });
 
@@ -257,7 +257,7 @@ describe('Module Helpers', () => {
       await project.build({
         experimental: {
           // reduce build output when comparing test failures
-          includeBrowserPolyfill: false,
+          extensionApi: 'chrome',
         },
       });
 

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

@@ -264,7 +264,7 @@
     await project.build({
       experimental: {
         // Simplify the build output for comparison
-        includeBrowserPolyfill: false,
+        extensionApi: 'chrome',
       },
       vite: () => ({
         build: {
@@ -275,7 +275,7 @@
     });
 
     expect(await project.serializeFile('.output/chrome-mv3/background.js'))
       .toMatchInlineSnapshot(`
         ".output/chrome-mv3/background.js
         ----------------------------------------
         import { l as logHello, i as initPlugins } from "./chunks/_virtual_wxt-plugins-OjKtWpmY.js";
@@ -345,7 +345,7 @@
     await project.build({
       experimental: {
         // Simplify the build output for comparison
-        includeBrowserPolyfill: false,
+        extensionApi: 'chrome',
       },
       vite: () => ({
         build: {
@@ -356,7 +356,7 @@
     });
 
     expect(await project.serializeFile('.output/chrome-mv3/background.js'))
       .toMatchInlineSnapshot(`
         ".output/chrome-mv3/background.js
         ----------------------------------------
         var _background = function() {

packages/wxt/e2e/tests/user-config.test.ts

@@ -102,7 +102,7 @@ describe('User Config', () => {
     const withPolyfill = await buildBackground();
     const withoutPolyfill = await buildBackground({
       experimental: {
-        includeBrowserPolyfill: false,
+        extensionApi: 'chrome',
       },
     });
     expect(withoutPolyfill).not.toBe(withPolyfill);

packages/wxt/package.json

@@ -46,8 +46,16 @@
       "default": "./dist/sandbox/index.mjs"
     },
     "./browser": {
-      "types": "./dist/browser.d.ts",
-      "default": "./dist/browser.mjs"
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.mjs"
+    },
+    "./browser/chrome": {
+      "types": "./dist/browser/chrome.d.ts",
+      "import": "./dist/browser/chrome.mjs"
+    },
+    "./browser/webextension-polyfill": {
+      "types": "./dist/browser/webextension-polyfill.d.ts",
+      "import": "./dist/browser/webextension-polyfill.mjs"
     },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
@@ -121,6 +129,7 @@
   "devDependencies": {
     "@aklinker1/check": "^1.3.1",
     "@faker-js/faker": "^8.4.1",
+    "@types/chrome": "^0.0.268",
     "@types/fs-extra": "^11.0.4",
     "@types/lodash.merge": "^4.6.9",
     "@types/natural-compare": "^1.4.3",
@@ -138,5 +147,13 @@
     "unbuild": "^2.0.0",
     "vitest": "^2.0.3",
     "vitest-plugin-random-seed": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@types/chrome": "*"
+  },
+  "peerDependenciesMeta": {
+    "@types/chrome": {
+      "optional": true
+    }
   }
 }

packages/wxt/src/types/modules.d.ts → packages/wxt/src/@types/modules.d.ts

@@ -49,8 +49,3 @@ declare module 'web-ext-run/util/logger' {
   }
   export const consoleStream: IConsoleStream;
 }
-
-declare module 'wxt/browser' {
-  // Overridden when types are generated per project
-  export type PublicPath = string;
-}

packages/wxt/src/__tests__/storage.test.ts

@@ -1,6 +1,6 @@
 import { fakeBrowser } from '@webext-core/fake-browser';
 import { describe, it, expect, beforeEach, vi, expectTypeOf } from 'vitest';
-import { browser } from '../browser';
+import { browser } from 'wxt/browser';
 import { WxtStorageItem, storage } from '../storage';
 
 /**

packages/wxt/src/browser/chrome.ts

@@ -0,0 +1,23 @@
+/// <reference types="chrome" />
+
+export type Browser = typeof chrome;
+
+export type AugmentedBrowser = Browser & {
+  runtime: WxtRuntime;
+  i18n: WxtI18n;
+};
+
+export interface WxtRuntime {
+  // Overriden per-project
+}
+
+export interface WxtI18n {
+  // Overriden per-project
+}
+
+export const browser: AugmentedBrowser =
+  // @ts-expect-error
+  globalThis.browser?.runtime?.id == null
+    ? globalThis.chrome
+    : // @ts-expect-error
+      globalThis.browser;

packages/wxt/src/browser/index.ts

@@ -0,0 +1,4 @@
+/**
+ * @module wxt/browser
+ */
+export * from './webextension-polyfill';

packages/wxt/src/browser.ts → packages/wxt/src/browser/webextension-polyfill.ts

@@ -1,6 +1,3 @@
-/**
- * @module wxt/browser
- */
 import originalBrowser, { Browser, Runtime, I18n } from 'webextension-polyfill';
 
 export interface AugmentedBrowser extends Browser {

packages/wxt/src/client/content-scripts/content-script-context.ts

@@ -1,5 +1,5 @@
 import { ContentScriptDefinition } from '../../types';
-import { browser } from '../../browser';
+import { browser } from 'wxt/browser';
 import { logger } from '../../sandbox/utils/logger';
 import { WxtLocationChangeEvent, getUniqueEventName } from './custom-events';
 import { createLocationWatcher } from './location-watcher';

packages/wxt/src/client/content-scripts/custom-events.ts

@@ -1,4 +1,4 @@
-import { browser } from '../../browser';
+import { browser } from 'wxt/browser';
 
 export class WxtLocationChangeEvent extends Event {
   static EVENT_NAME = getUniqueEventName('wxt:locationchange');
@@ -22,5 +22,5 @@ export function getUniqueEventName(eventName: string): string {
       ? 'build'
       : import.meta.env.ENTRYPOINT;
 
-  return `${browser.runtime.id}:${entrypointName}:${eventName}`;
+  return `${browser?.runtime?.id}:${entrypointName}:${eventName}`;
 }

packages/wxt/src/client/content-scripts/ui/index.ts

@@ -1,4 +1,4 @@
-import { browser } from '../../../browser';
+import { browser } from 'wxt/browser';
 import { ContentScriptContext } from '..';
 import {
   ContentScriptAnchoredOptions,

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

@@ -66,7 +66,7 @@ export async function createViteBuilder(
       wxtPlugins.tsconfigPaths(wxtConfig),
       wxtPlugins.noopBackground(),
       wxtPlugins.globals(wxtConfig),
-      wxtPlugins.excludeBrowserPolyfill(wxtConfig),
+      wxtPlugins.resolveExtensionApi(wxtConfig),
       wxtPlugins.defineImportMeta(),
       wxtPlugins.wxtPluginLoader(wxtConfig),
       wxtPlugins.resolveAppConfig(wxtConfig),

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

@@ -9,7 +9,7 @@ export * from './cssEntrypoints';
 export * from './bundleAnalysis';
 export * from './globals';
 export * from './webextensionPolyfillMock';
-export * from './excludeBrowserPolyfill';
+export * from './resolveExtensionApi';
 export * from './entrypointGroupGlobals';
 export * from './defineImportMeta';
 export * from './removeEntrypointMainFunction';

packages/wxt/src/core/builders/vite/plugins/resolveExtensionApi.ts

@@ -0,0 +1,27 @@
+import { ResolvedConfig } from '../../../../types';
+import type * as vite from 'vite';
+
+/**
+ * Apply the experimental config for which extension API is used. This only
+ * effects the extension API included at RUNTIME - during development, types
+ * depend on the import.
+ *
+ * NOTE: this only works if we import `wxt/browser` instead of using the relative path.
+ */
+export function resolveExtensionApi(config: ResolvedConfig): vite.Plugin {
+  return {
+    name: 'wxt:resolve-extension-api',
+    config() {
+      // Only apply the config if we're disabling the polyfill
+      if (config.experimental.extensionApi === 'webextension-polyfill') return;
+
+      return {
+        resolve: {
+          alias: [
+            { find: /^wxt\/browser$/, replacement: 'wxt/browser/chrome' },
+          ],
+        },
+      };
+    },
+  };
+}

packages/wxt/src/core/builders/vite/plugins/webextensionPolyfillMock.ts

@@ -29,6 +29,8 @@ export function webextensionPolyfillMock(
               config.wxtModuleDir,
               'dist/virtual/mock-browser',
             ),
+            'wxt/browser': 'wxt/testing',
+            'wxt/browser/chrome': 'wxt/testing',
           },
         },
         ssr: {

packages/wxt/src/core/utils/building/rebuild.ts

@@ -1,4 +1,4 @@
-import type { Manifest } from '../../../browser';
+import type { Manifest } from 'wxt/browser';
 import { BuildOutput, Entrypoint, EntrypointGroup } from '../../../types';
 import { generateTypesDir } from './generate-wxt-dir';
 import { buildEntrypoints } from './build-entrypoints';

packages/wxt/src/core/utils/building/resolve-config.ts

@@ -175,7 +175,7 @@ export async function resolveConfig(
     userConfigMetadata: userConfigMetadata ?? {},
     alias,
     experimental: defu(mergedConfig.experimental, {
-      includeBrowserPolyfill: true,
+      extensionApi: 'webextension-polyfill' as const,
       entrypointImporter: 'jiti' as const,
     }),
     dev: {

packages/wxt/src/core/utils/content-scripts.ts

@@ -1,4 +1,4 @@
-import type { Manifest, Scripting } from '../../browser';
+import type { Manifest, Scripting } from 'wxt/browser';
 import { ContentScriptEntrypoint, ResolvedConfig } from '../../types';
 import { getEntrypointBundlePath } from './entrypoints';
 

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

@@ -1,4 +1,4 @@
-import type { Manifest } from '../../browser';
+import type { Manifest } from 'wxt/browser';
 import {
   Entrypoint,
   BackgroundEntrypoint,

packages/wxt/src/core/utils/testing/fake-objects.ts

@@ -4,7 +4,7 @@
 import { resolve } from 'path';
 import { faker } from '@faker-js/faker';
 import merge from 'lodash.merge';
-import { Commands, type Manifest } from '../../../browser';
+import { Commands, type Manifest } from 'wxt/browser';
 import {
   FsCache,
   ResolvedConfig,
@@ -297,7 +297,7 @@ export const fakeResolvedConfig = fakeObjectCreator<ResolvedConfig>(() => {
     userConfigMetadata: {},
     alias: {},
     experimental: {
-      includeBrowserPolyfill: true,
+      extensionApi: 'webextension-polyfill',
       entrypointImporter: 'jiti',
     },
     dev: {

packages/wxt/src/storage.ts

@@ -5,7 +5,7 @@
  *
  * @module wxt/storage
  */
-import { Storage, browser } from './browser';
+import { Storage, browser } from 'wxt/browser';
 import { dequal } from 'dequal/lite';
 import { logger } from './sandbox/utils/logger';
 import { toArray } from './core/utils/arrays';

packages/wxt/src/types/index.ts → packages/wxt/src/types.ts

@@ -1,8 +1,8 @@
 import type * as vite from 'vite';
-import type { Manifest, Scripting } from '../browser';
+import type { Manifest, Scripting } from 'wxt/browser';
 import { UnimportOptions, Import } from 'unimport';
 import { LogLevel } from 'consola';
-import { ContentScriptContext } from '../client/content-scripts/content-script-context';
+import type { ContentScriptContext } from './client/content-scripts/content-script-context';
 import type { PluginVisualizerOptions } from '@aklinker1/rollup-plugin-visualizer';
 import type { FSWatcher } from 'chokidar';
 import { ResolvedConfig as C12ResolvedConfig } from 'c12';
@@ -297,25 +297,12 @@ export interface InlineConfig {
    */
   experimental?: {
     /**
-     * Whether to use [`webextension-polyfill`](https://www.npmjs.com/package/webextension-polyfill)
-     * when importing `browser` from `wxt/browser`.
+     * Which extension API to use. To switch to `"chrome"`, make sure to
+     * install the `@types/chrome` package.
      *
-     * When set to `false`, WXT will export the chrome global instead of the polyfill from
-     * `wxt/browser`.
-     *
-     * You should use `browser` to access the web extension APIs.
-     *
-     * @experimental This option will remain experimental until Manifest V2 is dead.
-     *
-     * @default true
-     * @example
-     * export default defineConfig({
-     *   experimental: {
-     *     includeBrowserPolyfill: false
-     *   }
-     * })
+     * @default "webextension-polyfill"
      */
-    includeBrowserPolyfill?: boolean;
+    extensionApi?: 'webextension-polyfill' | 'chrome';
     /**
      * Method used to import entrypoint files during the build process to extract their options.
      *
@@ -1203,7 +1190,7 @@ export interface ResolvedConfig {
    */
   alias: Record<string, string>;
   experimental: {
-    includeBrowserPolyfill: boolean;
+    extensionApi: 'webextension-polyfill' | 'chrome';
     entrypointImporter: 'jiti' | 'vite-runtime' | 'vite-node';
   };
   dev: {

packages/wxt/src/virtual/fake-browser-webextension-polyfill.ts

@@ -0,0 +1,3 @@
+import { fakeBrowser } from 'wxt/testing';
+
+export const browser = fakeBrowser;