fix!: Make web-ext a peer dependency

docs/guide/essentials/config/browser-startup.md

@@ -4,11 +4,23 @@ outline: deep
 
 # Browser Startup
 
-> See the [API Reference](/api/reference/wxt/interfaces/WebExtConfig) for a full list of config.
+During development, WXT will use any of the below packages to automatically open a browser with your extension installed.
+
+- [`web-ext` by Mozilla](https://www.npmjs.com/package/web-ext)
+
+Just install the dependency you want WXT to use to open the browser.
+
+## Disable Opening Browser
 
-During development, WXT uses [`web-ext` by Mozilla](https://www.npmjs.com/package/web-ext) to automatically open a browser window with your extension installed.
+To disable automatic startup, uninstall all these packages.
+
+`web-ext` comes installed if you created your project using WXT's starter templates.
+
+## `web-ext` Usage
+
+> See the [API Reference](/api/reference/wxt/interfaces/WebExtConfig) for a full list of config.
 
-## Config Files
+### Config Files
 
 You can configure browser startup in 3 places:
 
@@ -25,9 +37,9 @@ You can configure browser startup in 3 places:
 2. `<rootDir>/wxt.config.ts`: Via the [`webExt` config](/api/reference/wxt/interfaces/InlineConfig#webext), included in version control
 3. `$HOME/web-ext.config.ts`: Provide default values for all WXT projects on your computer
 
-## Recipes
+### Recipes
 
-### Set Browser Binaries
+#### Set Browser Binaries
 
 To set or customize the browser opened during development:
 
@@ -57,7 +69,7 @@ export default defineConfig({
 
 By default, WXT will try to automatically discover where Chrome/Firefox are installed. However, if you have chrome installed in a non-standard location, you need to set it manually as shown above.
 
-### Persist Data
+#### Persist Data
 
 By default, to keep from modifying your browser's existing profiles, `web-ext` creates a brand new profile every time you run the `dev` script.
 
@@ -94,9 +106,9 @@ Now, next time you run the `dev` script, a persistent profile will be created in
 You can use any directory you'd like for `--user-data-dir`, the examples above create a persistent profile for each WXT project. To create a profile for all WXT projects, you can put the `chrome-data` directory inside your user's home directory.
 :::
 
-### Disable Opening Browser
+#### Disable Opening Browser
 
-If you prefer to load the extension into your browser manually, you can disable the auto-open behavior:
+If you don't want to uninstall `web-ext`, like to test in your normal profile, you can do so via `disabled: true`:
 
 ```ts [web-ext.config.ts]
 import { defineWebExtConfig } from 'wxt';

docs/guide/resources/upgrading.md

@@ -35,6 +35,39 @@ Listed below are all the breaking changes you should address when upgrading to a
 
 Currently, WXT is in pre-release. This means changes to the second digit, `v0.X`, are considered major and have breaking changes. Once v1 is released, only major version bumps will have breaking changes.
 
+## v0.20.0 → vX.Y.Z
+
+### Dev Browser Startup
+
+The package used to open the browser on startup has changed. Previously, WXT used `web-ext-run` as a direct dependency, but now we use `web-ext` as a peer dependency.
+
+:::details
+
+`web-ext-run` was a light-weight fork of `web-ext`, but it was difficult to maintain and quickly got out-of-date compared to `web-ext`.
+
+:::
+
+In v0.20, how automatic startup is enabled/disabled has changed:
+
+- To continue opening the browser automatically, add `web-ext` as a dependency. No changes are required in your `web-ext.config.ts` files.
+
+  ```sh
+  pnpm add -D web-ext
+  ```
+
+- To disable the browser automatically, **_DON'T_** add `web-ext` as a dependency. Additionally, you can remove any `web-ext.config.ts` files since they're not used if `web-ext` isn't installed:
+
+  ```sh
+  rm web-ext.config.ts
+
+  # Keep the config in your home dir until all your projects have been upgraded
+  rm ~/web-ext.config.ts
+  ```
+
+## New Deprecations
+
+- `wxt.config.runnerConfig` renamed to `wxt.config.webExt`. `runnerConfig` be removed in next major release.
+
 ## v0.19.0 → v0.20.0
 
 v0.20 is a big release! There are lots of breaking changes because this version is intended to be a release candidate for v1.0. If all goes well, v1.0 will be released with no additional breaking changes.

packages/wxt/package.json

@@ -57,11 +57,11 @@
     "prompts": "^2.4.2",
     "publish-browser-extension": "^2.3.0 || ^3.0.2 || ^4.0.0",
     "scule": "^1.3.0",
-    "unimport": "^3.13.1 || ^4.0.0 || ^5.0.0",
-    "web-ext-run": "^0.2.4"
+    "unimport": "^3.13.1 || ^4.0.0 || ^5.0.0"
   },
   "peerDependencies": {
-    "vite": "^6.3.4 || ^7.0.0"
+    "vite": "^6.3.4 || ^7.0.0",
+    "web-ext": ">=9.2.0"
   },
   "devDependencies": {
     "@faker-js/faker": "^10.2.0",
@@ -78,9 +78,14 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
     "vitest": "^4.0.18",
-    "vitest-plugin-random-seed": "^1.1.2"
+    "vitest-plugin-random-seed": "^1.1.2",
+    "web-ext": "^9.2.0"
+  },
+  "peerDependenciesMeta": {
+    "web-ext": {
+      "optional": true
+    }
   },
-  "peerDependenciesMeta": {},
   "repository": {
     "type": "git",
     "url": "git+https://github.com/wxt-dev/wxt.git"

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

@@ -17,7 +17,7 @@ declare module 'zip-dir' {
   export = zipdir;
 }
 
-declare module 'web-ext-run' {
+declare module 'web-ext' {
   export interface WebExtRunInstance {
     reloadAllExtensions(): Promise<void>;
     exit(): Promise<void>;
@@ -31,7 +31,7 @@ declare module 'web-ext-run' {
   export default webExt;
 }
 
-declare module 'web-ext-run/util/logger' {
+declare module 'web-ext/util/logger' {
   // https://github.com/mozilla/web-ext/blob/e37e60a2738478f512f1255c537133321f301771/src/util/logger.js#L43
   export interface IConsoleStream {
     stopCapturing(): void;

packages/wxt/src/core/create-server.ts

@@ -18,7 +18,6 @@ import {
   rebuild,
   findEntrypoints,
 } from './utils/building';
-import { createExtensionRunner } from './runners';
 import { Mutex } from 'async-mutex';
 import pc from 'picocolors';
 import { relative } from 'node:path';
@@ -56,10 +55,7 @@ async function createServerInternal(): Promise<WxtDevServer> {
     return { host, port, origin };
   };
 
-  let [runner, builderServer] = await Promise.all([
-    createExtensionRunner(),
-    wxt.builder.createServer(getServerInfo()),
-  ]);
+  let builderServer = await wxt.builder.createServer(getServerInfo());
 
   // Used to track if modules need to be re-initialized
   let wasStopped = false;
@@ -86,7 +82,6 @@ async function createServerInternal(): Promise<WxtDevServer> {
     async start() {
       if (wasStopped) {
         await wxt.reloadConfig();
-        runner = await createExtensionRunner();
         builderServer = await wxt.builder.createServer(getServerInfo());
         await initWxtModules();
       }
@@ -119,14 +114,15 @@ async function createServerInternal(): Promise<WxtDevServer> {
 
       keyboardShortcuts.printHelp({
         canReopenBrowser:
-          !wxt.config.runnerConfig.config.disabled && !!runner.canOpen?.(),
+          !wxt.config.runnerConfig.config.disabled &&
+          !!wxt.config.runner.canOpen?.(),
       });
     },
 
     async stop() {
       wasStopped = true;
       keyboardShortcuts.stop();
-      await runner.closeBrowser();
+      await wxt.config.runner.closeBrowser();
       await builderServer.close();
       await wxt.hooks.callHook('server:closed', wxt, server);
 
@@ -150,11 +146,10 @@ async function createServerInternal(): Promise<WxtDevServer> {
       server.ws.send('wxt:reload-extension');
     },
     async restartBrowser() {
-      await runner.closeBrowser();
+      await wxt.config.runner.closeBrowser();
       keyboardShortcuts.stop();
       await wxt.reloadConfig();
-      runner = await createExtensionRunner();
-      await runner.openBrowser();
+      await wxt.config.runner.openBrowser();
       keyboardShortcuts.start();
     },
   };
@@ -190,7 +185,7 @@ async function createServerInternal(): Promise<WxtDevServer> {
     }
 
     // Open browser after everything is ready to go.
-    await runner.openBrowser();
+    await wxt.config.runner.openBrowser();
   };
 
   builderServer.on?.('close', () => keyboardShortcuts.stop());

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

@@ -14,6 +14,7 @@ import {
   WxtModule,
   WxtModuleWithMetadata,
   ResolvedEslintrc,
+  ExtensionRunner,
 } from '../types';
 import path from 'node:path';
 import { createFsCache } from './utils/cache';
@@ -29,6 +30,10 @@ import { safeStringToNumber } from './utils/number';
 import { loadEnv } from './utils/env';
 import { getPort } from 'get-port-please';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createSafariRunner } from './runners/safari';
+import isWsl from 'is-wsl';
+import { createWslRunner } from './runners/wsl';
+import { createManualRunner } from './runners/manual';
 
 /**
  * Given an inline config, discover the config file if necessary, merge the results, resolve any
@@ -124,7 +129,7 @@ export async function resolveConfig(
       '`InlineConfig#runner` is deprecated, use `InlineConfig#webExt` instead. See https://wxt.dev/guide/resources/upgrading.html#v0-19-0-rarr-v0-20-0',
     );
   }
-  const runnerConfig = await loadConfig<WebExtConfig>({
+  const webExt = await loadConfig<WebExtConfig>({
     name: 'web-ext',
     cwd: root,
     globalRc: true,
@@ -217,7 +222,9 @@ export async function resolveConfig(
     publicDir,
     wxtModuleDir,
     root,
-    runnerConfig,
+    runnerConfig: webExt,
+    webExt,
+    runner: await resolveRunner(browser, logger, mergedConfig),
     srcDir,
     typesDir,
     wxtDir,
@@ -651,3 +658,26 @@ export async function resolveWxtUserModules(
   );
   return [...npmModules, ...localModules];
 }
+
+async function resolveRunner(
+  browser: string,
+  logger: Logger,
+  mergedConfig: InlineConfig,
+): Promise<ExtensionRunner> {
+  if (browser === 'safari') return createSafariRunner();
+
+  if (isWsl) return createWslRunner();
+
+  try {
+    // This module imports `web-ext`, so if it fails, we know `web-ext` isn't installed
+    const { createWebExtRunner } = await import('./runners/web-ext');
+    return mergedConfig.webExt?.disabled
+      ? createManualRunner()
+      : createWebExtRunner();
+  } catch (err) {
+    logger.debug('Error loading the web-ext runner', err);
+    // TODO: only ignore "web-ext module not found" errors
+  }
+
+  return createManualRunner();
+}