WXT Web Extension Framework

0.20.25 · active · verified Sun Apr 19

WXT is a next-generation web extension framework designed for building browser extensions across all major browsers (Chrome, Firefox, Edge, etc.) supporting both Manifest V2 and Manifest V3. It leverages Vite for fast development with Hot Module Replacement (HMR) and rapid reloads. The current stable version is `0.20.25`. WXT follows a frequent release cadence, often releasing multiple patch versions within weeks, indicating active development and responsiveness to bug fixes and minor enhancements. Key differentiators include its file-based entrypoints, comprehensive TypeScript support, auto-imports, a flexible module system for code reuse, and framework agnosticism, allowing integration with popular UI libraries like Vue, React, and Svelte via dedicated modules. It also provides automated publishing capabilities and bundle analysis.

Common errors

```
Error: Node.js v18.x is not supported. Please use Node.js v20.12.0 or higher.
```
cause Using an outdated Node.js version that does not meet WXT's engine requirements.

fix Upgrade Node.js to version `20.12.0` or newer (e.g., using `nvm install 20` and `nvm use 20`). Alternatively, use Bun version `1.2.0` or higher.
```
Peer dependency 'eslint' is not installed or incompatible.
```
cause The required `eslint` package is either missing from `devDependencies` or its version does not satisfy WXT's peer dependency range.

fix Install `eslint` with `npm install -D eslint@'^8.57.0 || ^9.0.0 || ^10.0.0'` to match the expected peer dependency range.
```
Error: Cannot find module 'vite'
```
cause Vite is a fundamental dependency, and issues can arise if it's not correctly installed or if WXT's internal Vite resolution fails.

fix Ensure `vite` is installed as a `devDependency` (`npm install -D vite`) and that WXT is updated to a version compatible with your Vite installation (e.g., `wxt@0.20.19` for Vite 8 support).

Warnings

breaking WXT now requires Node.js version >=20.12.0 or Bun >=1.2.0. Older Node.js versions are not supported and will prevent the framework from running.
Fix: Upgrade your Node.js runtime to `20.12.0` or higher, or use Bun `1.2.0` or higher.
breaking Major Vite version updates, specifically Vite 8, require corresponding WXT updates or module updates. Older WXT versions may not be compatible with newer Vite versions, leading to build failures or unexpected behavior.
Fix: Ensure you are using `wxt@0.20.19` or newer for Vite 8 compatibility. Update WXT-specific modules (e.g., `@wxt-dev/module-react`, `@wxt-dev/module-svelte`) to their latest versions to support newer Vite plugin versions.
gotcha The `eslint` peer dependency is critical for linting. WXT's internal tooling expects a compatible `eslint` version. Incompatible versions (e.g., older `eslint 8` with newer WXT versions expecting `eslint 9` or `10`) can lead to warnings or linting failures.
Fix: Install `eslint` as a dev dependency (`npm install -D eslint@'^8.57.0 || ^9.0.0 || ^10.0.0'`) ensuring it matches the specified peer dependency range.
gotcha Handling Manifest V2 (MV2) vs. Manifest V3 (MV3) requires careful attention to browser extension API differences, especially regarding background scripts, content script injection, and permissions. WXT aims to abstract some of this, but developers must still understand the underlying manifest requirements.
Fix: Consult the official WXT documentation on MV2/MV3 compatibility and browser-specific API changes. Test extensions thoroughly across target browsers and manifest versions.
deprecated Changes in dev server port assignment on reload (e.g., [#2283]) might affect automated testing or development setups that rely on fixed ports. While a fix was implemented, custom `dev.server.port` configurations should be reviewed.
Fix: Update to `wxt@0.20.25` or newer to ensure consistent dev server port behavior on reload. Consider using `dev.server.strictPort` for explicit port control if issues persist.

Install

npm install wxt npm
yarn add wxt yarn
pnpm add wxt pnpm

Imports

defineConfig
```
import { defineConfig } from 'wxt';
```
Used in `wxt.config.ts` for type-safe configuration. This is the primary programmatic entry point for customizing WXT's build process.
createViteConfig
```
import { createViteConfig } from 'wxt';
```
A utility function that can be used within `wxt.config.ts` to extend the underlying Vite configuration.
Wxt
wrong:
```
import { Wxt } from 'wxt';
```
correct:
```
import Wxt from 'wxt';
```
The primary WXT instance or CLI entry is typically used via `npx wxt` or `bunx wxt` and not directly imported into application code. If a programmatic API were to expose a default export, this would be the pattern, but `wxt` is largely a CLI-driven framework.

Quickstart

This quickstart demonstrates a basic `wxt.config.ts` file, defining entrypoints, manifest permissions, and host permissions for a typical web extension project. It illustrates the primary configuration method for WXT.

import { defineConfig } from 'wxt';

export default defineConfig({
  srcDir: 'src',
  publicDir: 'public',
  entrypoints: {
    background: 'src/background.ts',
    'content-scripts/inject': 'src/content-scripts/inject.ts',
    popup: 'src/popup/index.html',
    options: 'src/options/index.html',
  },
  manifest: {
    host_permissions: ['*://*.google.com/*', '*://*.bing.com/*'],
    permissions: ['storage', 'unlimitedStorage'],
    name: 'My Awesome Extension',
    version: '1.0.0',
    description: 'A quickstart web extension built with WXT.',
  },
  modules: {
    // Example: add the React module if using React
    // react: true,
  },
});

view raw JSON →