| name | chrome-extension-wxt |
| description | Build Chrome extensions using WXT framework with TypeScript, React, Vue, or Svelte. Use when creating browser extensions, developing cross-browser add-ons, or working with Chrome Web Store projects. Triggers on phrases like "chrome extension", "browser extension", "WXT framework", "manifest v3", or file patterns like wxt.config.ts. |
| metadata | {"version":"1.1.1"} |
Chrome Extension Development with WXT
Build modern, cross-browser extensions using WXT - the next-generation framework that supports Chrome, Firefox, Edge, Safari, and all Chromium browsers with a single codebase.
When to Use This Skill
Use this skill when:
- Creating a new Chrome/browser extension
- Setting up WXT development environment
- Building extension features (popup, content scripts, background scripts)
- Implementing cross-browser compatibility
- Working with Manifest V3 (mandatory standard as of 2025, V2 deprecated)
- Integrating React 19, Vue, Svelte, or Solid with extensions
Quick Start Workflow
1. Initialize WXT Project
npm create wxt@latest
npm create wxt@latest -- --template react-ts
npm create wxt@latest -- --template vue-ts
npm create wxt@latest -- --template svelte-ts
2. Project Structure
WXT uses file-based conventions:
project/
├── entrypoints/ # Auto-discovered entry points
│ ├── background.ts # Service worker
│ ├── content.ts # Content script
│ ├── popup.html # Popup UI
│ └── options.html # Options page
├── components/ # Auto-imported UI components
├── utils/ # Auto-imported utilities
├── public/ # Static assets
│ └── icon/ # Extension icons
├── wxt.config.ts # Configuration
└── package.json
3. Development Commands
npm run dev
npm run build
npm run zip
Core Entry Points
WXT recognizes entry points by filename in entrypoints/ directory:
Background Script (Service Worker)
export default defineBackground({
type: 'module',
persistent: false,
main() {
browser.action.onClicked.addListener((tab) => {
console.log('Extension clicked', tab);
});
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
sendResponse({ success: true });
return true;
});
},
});
Content Script
export default defineContentScript({
matches: ['*://*.example.com/*'],
runAt: 'document_end',
main(ctx) {
console.log('Content script loaded');
const ui = createShadowRootUi(ctx, {
name: 'my-extension-ui',
position: 'inline',
anchor: 'body',
onMount(container) {
const root = ReactDOM.createRoot(container);
root.render(<App />);
},
});
ui.mount();
},
});
Popup UI
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
ReactDOM.createRoot(document.getElementById('root')!).render(
<React.StrictMode>
<App />
</React.StrictMode>
);
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Extension Popup</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="./main.tsx"></script>
</body>
</html>
Configuration
Basic wxt.config.ts
import { defineConfig } from 'wxt';
export default defineConfig({
modules: ['@wxt-dev/module-react'],
manifest: {
name: 'My Extension',
description: 'Extension description',
permissions: ['storage', 'activeTab'],
host_permissions: ['*://example.com/*'],
},
browser: 'chrome',
});
Common Patterns
Type-Safe Storage
import { storage } from 'wxt/storage';
export const storageHelper = {
async get<T>(key: string): Promise<T | null> {
return await storage.getItem<T>(`local:${key}`);
},
async set<T>(key: string, value: T): Promise<void> {
await storage.setItem(`local:${key}`, value);
},
watch<T>(key: string, callback: (newValue: T | null) => void) {
return storage.watch<T>(`local:${key}`, callback);
},
};
Type-Safe Messaging
interface Messages {
'get-data': {
request: { key: string };
response: { value: any };
};
}
export async function sendMessage<K extends keyof Messages>(
type: K,
payload: Messages[K]['request']
): Promise<Messages[K]['response']> {
return await browser.runtime.sendMessage({ type, payload });
}
Script Injection
import { injectScript } from 'wxt/client';
await injectScript('/injected.js', {
keepInDom: false,
});
Building & Deployment
Production Build
npm run build -- --browser=chrome
npm run build -- --browser=firefox
npm run zip
npm run zip -- --browser=firefox
Firefox Support
Firefox differs from Chrome in important ways — see references/firefox.md for full details. Key gotchas:
- WXT defaults Firefox to MV2; pass
--mv3 explicitly (wxt build -b firefox --mv3).
- Firefox MV3 uses event pages (
background.scripts), not service workers — WXT generates the right manifest key per target.
browser_specific_settings.gecko.id is required to sign/publish MV3 extensions.- Firefox MV3 treats
host_permissions as optional — users can revoke them anytime; always check permissions.contains() before privileged work.
- AMO requires a source code ZIP alongside the extension ZIP (
wxt zip -b firefox produces both).
- Firefox-only APIs worth knowing:
contextualIdentities (containers), sidebarAction, menus, find, search, theme.
Multi-Browser Build
npm run zip:all
Output: .output/my-extension-{version}-{browser}.zip
Modern Stacks (2025)
Popular technology combinations for building Chrome extensions:
WXT + React + Tailwind + shadcn/ui
Most popular stack in 2025. Combines utility-first styling with pre-built accessible components.
npm create wxt@latest -- --template react-ts
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
npx shadcn@latest init
Best for: Modern UIs with consistent design system
Example: https://github.com/imtiger/wxt-react-shadcn-tailwindcss-chrome-extension
WXT + React + Mantine UI
Complete component library with 100+ components and built-in dark mode.
npm create wxt@latest -- --template react-ts
npm install @mantine/core @mantine/hooks
Best for: Feature-rich extensions needing complex components
Example: https://github.com/ongkay/WXT-Mantine-Tailwind-Browser-Extension
WXT + React + TypeScript (Minimal)
Clean setup for custom designs without UI library dependencies.
npm create wxt@latest -- --template react-ts
Best for: Simple extensions or highly custom designs
Advanced Topics
For detailed information on advanced topics, see the reference files:
- React Integration: See
references/react-integration.md for complete React setup, hooks, state management, and popular UI libraries
- Chrome APIs: See
references/chrome-api.md for comprehensive Chrome Extension API reference with examples
- Chrome 140+ Features: See
references/chrome-140-features.md for latest Chrome Extension APIs (sidePanel.getLayout(), etc.)
- WXT API: See
references/wxt-api.md for complete WXT framework API documentation
- Best Practices: See
references/best-practices.md for security, performance, and architecture patterns
Troubleshooting
Common issues and solutions:
- Module not found errors: Ensure modules are installed and properly imported
- CSP violations: Update
content_security_policy in manifest
- Hot reload not working: Check browser console for errors
- Storage not persisting: Use
storage.local or storage.sync correctly
For detailed troubleshooting, see references/troubleshooting.md
Resources
Official Documentation
Bundled Resources
- scripts/: Helper utilities for common extension tasks
- references/: Detailed documentation for advanced features
- assets/: Starter templates and example components
Use these resources as needed when building your extension.
