---
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.0"
---
# 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
```bash
# Create new project with framework of choice
npm create wxt@latest
# Or with specific template
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
```bash
npm run dev # Start dev server with HMR
npm run build # Production build
npm run zip # Package for store submission
```
## Core Entry Points
WXT recognizes entry points by filename in `entrypoints/` directory:
### Background Script (Service Worker)
```typescript
// entrypoints/background.ts
export default defineBackground({
type: 'module',
persistent: false,
main() {
// Listen for extension events
browser.action.onClicked.addListener((tab) => {
console.log('Extension clicked', tab);
});
// Handle messages
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
// Handle message
sendResponse({ success: true });
return true; // Keep channel open for async
});
},
});
```
### Content Script
```typescript
// entrypoints/content.ts
export default defineContentScript({
matches: ['*://*.example.com/*'],
runAt: 'document_end',
main(ctx) {
// Content script logic
console.log('Content script loaded');
// Create UI
const ui = createShadowRootUi(ctx, {
name: 'my-extension-ui',
position: 'inline',
anchor: 'body',
onMount(container) {
// Mount React/Vue component
const root = ReactDOM.createRoot(container);
root.render();
},
});
ui.mount();
},
});
```
### Popup UI
```typescript
// entrypoints/popup/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
ReactDOM.createRoot(document.getElementById('root')!).render(
);
```
```html
Extension Popup
```
## Configuration
### Basic wxt.config.ts
```typescript
import { defineConfig } from 'wxt';
export default defineConfig({
// Framework integration
modules: ['@wxt-dev/module-react'],
// Manifest configuration
manifest: {
name: 'My Extension',
description: 'Extension description',
permissions: ['storage', 'activeTab'],
host_permissions: ['*://example.com/*'],
},
// Browser target
browser: 'chrome', // or 'firefox', 'edge', 'safari'
});
```
## Common Patterns
### Type-Safe Storage
```typescript
// utils/storage.ts
import { storage } from 'wxt/storage';
export const storageHelper = {
async get(key: string): Promise {
return await storage.getItem(`local:${key}`);
},
async set(key: string, value: T): Promise {
await storage.setItem(`local:${key}`, value);
},
watch(key: string, callback: (newValue: T | null) => void) {
return storage.watch(`local:${key}`, callback);
},
};
```
### Type-Safe Messaging
```typescript
// utils/messaging.ts
interface Messages {
'get-data': {
request: { key: string };
response: { value: any };
};
}
export async function sendMessage(
type: K,
payload: Messages[K]['request']
): Promise {
return await browser.runtime.sendMessage({ type, payload });
}
```
### Script Injection
```typescript
// Inject script into page context
import { injectScript } from 'wxt/client';
await injectScript('/injected.js', {
keepInDom: false,
});
```
## Building & Deployment
### Production Build
```bash
# Build for specific browser
npm run build -- --browser=chrome
npm run build -- --browser=firefox
# Create store-ready ZIP
npm run zip
npm run zip -- --browser=firefox
```
### Multi-Browser Build
```bash
# Build for all browsers
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.
```bash
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.
```bash
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.
```bash
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:
1. **Module not found errors**: Ensure modules are installed and properly imported
2. **CSP violations**: Update `content_security_policy` in manifest
3. **Hot reload not working**: Check browser console for errors
4. **Storage not persisting**: Use `storage.local` or `storage.sync` correctly
For detailed troubleshooting, see `references/troubleshooting.md`
## Resources
### Official Documentation
- WXT Docs: https://wxt.dev
- Chrome Extension Docs: https://developer.chrome.com/docs/extensions
- Firefox Extension Docs: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons
### 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.