Development

WXT's main goal is providing the best DX it possibly can. When running your extension in dev mode, each part of your extension is reloaded separately when possible.

	HMR	Reloaded individually	Reload extension	Restart browser
HTML File		✅
HTML Dependency	✅
MV3 Content Script		✅
MV2 Content Script			✅
Background			✅
manifest.json				🟡 See #16
wxt.config.ts				🟡 See #10
web-ext.config.ts				🟡 See #10

Configure Browser Startup

WXT uses web-ext by Mozilla to automatically open a browser with the extension installed. You can configure the runner's behavior via the runner option, or in a separate gitignored file, web-ext.config.ts.

wxt.config.ts

import { defineConfig } from 'wxt';

export default defineConfig({
  runner: {
    // Runner config
  },
});

web-ext.config.ts

import { defineRunnerConfig } from 'wxt';

export default defineRunnerConfig({
  // Runner config
});

Browser Binaries

web-ext's browser discovery is very limitted. By default, it only guesses at where Chrome and Firefox are installed. If you've customized your install locations, you may need to tell web-ext where the binaries/executables are located using the binaries option. For other Chromium based browsers, like Edge or Opera, you'll need to explicitly list them in the binaries option as well, otherwise they will open in Chrome by default.

// ~/web-ext.config.ts
import { defineRunnerConfig } from 'wxt';

export default defineRunnerConfig({
  binaries: {
    chrome: '/path/to/chrome-beta', // Use Chrome Beta instead of regular Chrome
    firefox: 'firefoxdeveloperedition', // Use Firefox Developer Edition instead of regular Firefox
    edge: '/path/to/edge', // Open MS Edge when running "wxt -b edge"
  },
});

TIP

When configuring browser binaries, it's helpful to put them in ~/web-ext.config.ts instead of the project directory's web-ext.config.ts file. When placed in your home directory (~/), this config will be used by all WXT projects, so you only need to configure the binaries once.

Other options

You can customize other options as well, like startup URLs, profiles, or additional command line arguments:

// web-ext.config.ts
import { defineRunnerConfig } from 'wxt';

export default defineRunnerConfig({
  startUrls: ['https://google.com', 'https://duckduckgo.com'],
  chromiumProfile: '/path/to/profile/to/use',
  chromiumArgs: ['--window-size=400x300'],
});

For a full list of options, see the API Reference.

Reload the Extension

Normally, to manually reload an extension, you have to visit chrome://extensions and click the reload button for your extension.

When running wxt command to start the dev server, WXT adds a keyboard shortcut, ctrl+E for Windows/Linux and cmd+E for Mac, that reloads the extension when pressed, without visiting chrome://extensions.

:::note This shortcut is only available during development, and is not be added to your extension when running wxt build or wxt-zip. :::