wxt

library0.20.25jsnpmunverified

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.

web-framework

npm install wxt

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WXT

wxt

web-frameworkjavascriptv0.20.25

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

✓ import Wxt from 'wxt';

✗ 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.

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, }, });

wxt --version

Debug

Known issues

breakingWXT 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.

affects: <=0.20.20

breakingMajor 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.

affects: <=0.20.18

gotchaThe `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.

affects: >=0.20.19

gotchaHandling 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.

affects: all

deprecatedChanges 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.

affects: <=0.20.24

Errors

Common errors & fixes

Error: Node.js v18.x is not supported. Please use Node.js v20.12.0 or higher.

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.

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'

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).

Upgrade

Version history

0.20.25latest on npm

Audit

Dependencies

eslintrequiredPeer dependency for linting projects scaffolded or managed by WXT. Supports multiple major versions.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/wxt-dev/wxt ↗

packagehttps://www.npmjs.com/package/wxt ↗

homepagehttps://wxt.dev ↗