WXT - Browser Extension Framework
When to Use
Apply this skill when:
- Project has
wxt.config.tsin root - Code uses
defineBackground,defineContentScript,defineUnlistedScript package.jsonhaswxtas a dependency- Entrypoints directory contains extension entry files
- Code imports from
#importsorwxt/*
Quick Reference
| Topic | Reference |
|---|---|
| Configuration, manifest, env vars, TypeScript | references/config.md |
| Entrypoints (background, HTML pages, unlisted) | references/entrypoints.md |
| Content scripts (UI, main world, SPA) | references/content-scripts.md |
| Storage API, defineItem, migrations, watchers | references/storage.md |
| Messaging (cross-context communication) | references/messaging.md |
| Testing with WxtVitest and fakeBrowser | references/testing.md |
| WXT modules (using and creating) | references/modules.md |
| Multi-browser builds and runtime detection | references/multi-browser.md |
| Vue, React, Svelte, Solid setup | references/frontend-frameworks.md |
| Common patterns and anti-patterns | references/patterns.md |
Most Common Pattern
// entrypoints/background.ts
export default defineBackground({
main() {
// ALL runtime code must be inside main() - cannot be async
browser.runtime.onInstalled.addListener(() => {
console.log('Extension installed');
});
},
});
Critical: main() cannot be async. Code outside main() runs at build time in Node.js.