{"id":12682,"library":"wxt","title":"WXT Web Extension Framework","description":"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.","status":"active","version":"0.20.25","language":"javascript","source_language":"en","source_url":"https://github.com/wxt-dev/wxt","tags":["javascript","vite","chrome","web","extension","browser","bundler","framework","typescript"],"install":[{"cmd":"npm install wxt","lang":"bash","label":"npm"},{"cmd":"yarn add wxt","lang":"bash","label":"yarn"},{"cmd":"pnpm add wxt","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for linting projects scaffolded or managed by WXT. Supports multiple major versions.","package":"eslint","optional":false}],"imports":[{"note":"Used in `wxt.config.ts` for type-safe configuration. This is the primary programmatic entry point for customizing WXT's build process.","symbol":"defineConfig","correct":"import { defineConfig } from 'wxt';"},{"note":"A utility function that can be used within `wxt.config.ts` to extend the underlying Vite configuration.","symbol":"createViteConfig","correct":"import { createViteConfig } from 'wxt';"},{"note":"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.","wrong":"import { Wxt } from 'wxt';","symbol":"Wxt","correct":"import Wxt from 'wxt';"}],"quickstart":{"code":"import { defineConfig } from 'wxt';\n\nexport default defineConfig({\n  srcDir: 'src',\n  publicDir: 'public',\n  entrypoints: {\n    background: 'src/background.ts',\n    'content-scripts/inject': 'src/content-scripts/inject.ts',\n    popup: 'src/popup/index.html',\n    options: 'src/options/index.html',\n  },\n  manifest: {\n    host_permissions: ['*://*.google.com/*', '*://*.bing.com/*'],\n    permissions: ['storage', 'unlimitedStorage'],\n    name: 'My Awesome Extension',\n    version: '1.0.0',\n    description: 'A quickstart web extension built with WXT.',\n  },\n  modules: {\n    // Example: add the React module if using React\n    // react: true,\n  },\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js runtime to `20.12.0` or higher, or use Bun `1.2.0` or higher.","message":"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.","severity":"breaking","affected_versions":"<=0.20.20"},{"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.","message":"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.","severity":"breaking","affected_versions":"<=0.20.18"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.20.19"},{"fix":"Consult the official WXT documentation on MV2/MV3 compatibility and browser-specific API changes. Test extensions thoroughly across target browsers and manifest versions.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<=0.20.24"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Using an outdated Node.js version that does not meet WXT's engine requirements.","error":"Error: Node.js v18.x is not supported. Please use Node.js v20.12.0 or higher."},{"fix":"Install `eslint` with `npm install -D eslint@'^8.57.0 || ^9.0.0 || ^10.0.0'` to match the expected peer dependency range.","cause":"The required `eslint` package is either missing from `devDependencies` or its version does not satisfy WXT's peer dependency range.","error":"Peer dependency 'eslint' is not installed or incompatible."},{"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).","cause":"Vite is a fundamental dependency, and issues can arise if it's not correctly installed or if WXT's internal Vite resolution fails.","error":"Error: Cannot find module 'vite'"}],"ecosystem":"npm"}