tomevault-io Browser Extension Development with WXT
Quick Start
# Create new extension
npx wxt@latest init my-extension
cd my-extension
# Development (Chrome)
npm run dev
# Development (Firefox)
npm run dev:firefox
# Build for production
npm run build
# Create ZIP for store submission
npm run zip
Project Structure
my-extension/
├── wxt.config.ts # WXT configuration
├── entrypoints/
│ ├── background.ts # Service worker
│ ├── content.ts # Content script
│ ├── popup/
│ │ ├── index.html
│ │ ├── main.tsx
│ │ └── App.tsx
│ └── options/
│ ├── index.html
│ └── main.tsx
├── components/ # Shared React components
├── assets/
│ └── icon.png # Auto-generates all sizes
├── public/ # Static files
├── package.json
└── tsconfig.json
Key difference from manual setup: No manifest.json — WXT generates it automatically from entrypoints and config.
WXT Configuration
// wxt.config.ts
import { defineConfig } from 'wxt';
export default defineConfig({
modules: ['@wxt-dev/module-react'],
manifest: {
name: 'My Extension',
description: 'A browser extension built with WXT',
permissions: ['storage', 'activeTab'],
host_permissions: ['https://*.example.com/*'],
},
});
Background Script (Service Worker)
// entrypoints/background.ts
export default defineBackground(() => {
console.log('Extension installed', { id: browser.runtime.id });
// Listen for messages
browser.runtime.onMessage.addListener((message, sender) => {
if (message.type === 'GET_DATA') {
return fetchData(); // Return promise for async response
}
});
// Context menu
browser.contextMenus.create({
id: 'my-action',
title: 'Do Something',
contexts: ['selection'],
});
browser.contextMenus.onClicked.addListener((info, tab) => {
if (info.menuItemId === 'my-action') {
console.log('Selected:', info.selectionText);
}
});
});
Content Script
// entrypoints/content.ts
export default defineContentScript({
matches: ['https://*.example.com/*'],
main() {
console.log('Content script loaded');
// DOM manipulation
const button = document.createElement('button');
button.textContent = 'My Extension';
button.onclick = () => {
browser.runtime.sendMessage({ type: 'BUTTON_CLICKED' });
};
document.body.appendChild(button);
// Listen for messages from background
browser.runtime.onMessage.addListener((message) => {
if (message.type === 'HIGHLIGHT') {
document.body.style.backgroundColor = 'yellow';
}
});
},
});
Content Script with UI (React)
// entrypoints/content.tsx
import ReactDOM from 'react-dom/client';
import App from './App';
export default defineContentScript({
matches: ['https://*.example.com/*'],
cssInjectionMode: 'ui',
main(ctx) {
const ui = createIntegratedUi(ctx, {
position: 'inline',
anchor: 'body',
onMount: (container) => {
const root = ReactDOM.createRoot(container);
root.render(<App />);
return root;
},
onRemove: (root) => {
root.unmount();
},
});
ui.mount();
},
});
Popup (React)
<!-- entrypoints/popup/index.html -->
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
</head>
<body>
<div id="root"></div>
<script type="module" src="./main.tsx"></script>
</body>
</html>
// entrypoints/popup/main.tsx
import ReactDOM from 'react-dom/client';
import App from './App';
import './style.css';
ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
// entrypoints/popup/App.tsx
import { useState, useEffect } from 'react';
import { storage } from 'wxt/storage';
// Type-safe storage
const enabledStorage = storage.defineItem<boolean>('sync:enabled', {
fallback: true,
});
export default function App() {
const [enabled, setEnabled] = useState(true);
useEffect(() => {
enabledStorage.getValue().then(setEnabled);
}, []);
const toggle = async () => {
const newValue = !enabled;
await enabledStorage.setValue(newValue);
setEnabled(newValue);
};
const handleAction = async () => {
const [tab] = await browser.tabs.query({ active: true, currentWindow: true });
if (tab.id) {
browser.tabs.sendMessage(tab.id, { type: 'HIGHLIGHT' });
}
};
return (
<div className="p-4 w-64">
<h1 className="text-lg font-bold mb-4">My Extension</h1>
<label className="flex items-center gap-2 mb-4">
<input type="checkbox" checked={enabled} />
Enabled
</label>
<button
className="w-full bg-blue-500 text-white py-2 rounded"
>
Do Something
</button>
</div>
);
}
Type-Safe Storage (WXT)
// utils/storage.ts
import { storage } from 'wxt/storage';
// Define typed storage items
export const settings = storage.defineItem<{
enabled: boolean;
theme: 'light' | 'dark';
apiKey?: string;
}>('sync:settings', {
fallback: {
enabled: true,
theme: 'light',
},
});
// Usage
const current = await settings.getValue();
await settings.setValue({ ...current, theme: 'dark' });
// Watch for changes
settings.watch((newValue) => {
console.log('Settings changed:', newValue);
});
Message Passing
// Define message types
interface Messages {
getData: { query: string };
highlight: { color: string };
}
// Background
browser.runtime.onMessage.addListener((message: Messages[keyof Messages]) => {
// Handle messages
});
// Content/Popup → Background
const response = await browser.runtime.sendMessage({ type: 'getData', query: 'test' });
// Background → Content
await browser.tabs.sendMessage(tabId, { type: 'highlight', color: 'yellow' });
Permissions
// wxt.config.ts
export default defineConfig({
manifest: {
// Required permissions (always active)
permissions: ['storage', 'activeTab'],
// Optional permissions (request at runtime)
optional_permissions: ['tabs', 'history'],
// Host permissions
host_permissions: ['https://*.example.com/*'],
optional_host_permissions: ['https://*/*'],
},
});
// Request optional permission
const granted = await browser.permissions.request({
permissions: ['tabs'],
origins: ['https://other-site.com/*'],
});
Cross-Browser Support
WXT handles browser differences automatically:
// Use `browser` namespace (works in all browsers)
browser.storage.sync.get(['key']);
browser.runtime.sendMessage({ type: 'test' });
// WXT polyfills Chrome's callback-based APIs to Promises
const tabs = await browser.tabs.query({ active: true });
Build for specific browser:
npm run build # Chrome (default)
npm run build:firefox # Firefox
npm run build:safari # Safari
npm run build:edge # Edge
Testing
Unit Tests (Vitest)
// tests/storage.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { fakeBrowser } from 'wxt/testing';
describe('Settings storage', () => {
beforeEach(() => {
fakeBrowser.reset();
});
it('saves and loads settings', async () => {
const { settings } = await import('../utils/storage');
await settings.setValue({ enabled: false, theme: 'dark' });
const result = await settings.getValue();
expect(result.enabled).toBe(false);
expect(result.theme).toBe('dark');
});
});
E2E Tests (Playwright)
import { test, expect } from '@playwright/test';
test('popup opens and toggles', async ({ page, context }) => {
// Load extension
const extensionId = // ... get from context
await page.goto(`chrome-extension://${extensionId}/popup.html`);
const checkbox = page.getByRole('checkbox');
await expect(checkbox).toBeChecked();
await checkbox.click();
await expect(checkbox).not.toBeChecked();
});
Common Patterns
Inject CSS
// entrypoints/content.ts
export default defineContentScript({
matches: ['https://*.example.com/*'],
css: ['./styles.css'], // Auto-injected
main() {
// ...
},
});
Run at Document Start
export default defineContentScript({
matches: ['*://*/*'],
runAt: 'document_start', // Before page loads
main() {
// Block/modify requests early
},
});
Alarms (Scheduled Tasks)
// entrypoints/background.ts
export default defineBackground(() => {
browser.alarms.create('sync', { periodInMinutes: 30 });
browser.alarms.onAlarm.addListener((alarm) => {
if (alarm.name === 'sync') {
syncData();
}
});
});
Publishing
Chrome Web Store
npm run zip # Creates .output/my-extension-x.x.x-chrome.zip
# Upload to Chrome Web Store Developer Dashboard
Required justifications for permissions:
| Permission | Example Justification |
|---|---|
storage |
Stores user preferences locally: enabled state, settings. No data transmitted externally. |
activeTab |
Used to apply extension functionality to the current tab when user clicks extension icon. |
tabs |
Required to detect current website URL and determine if extension should activate based on user settings. |
host_permissions: <all_urls> |
Required to inject extension functionality on any website user adds to their list. Only activates on sites explicitly selected by user. |
Warning: Broad host permissions (<all_urls>) trigger in-depth review (1-2 weeks vs days). If you only need specific sites, list them explicitly.
Store description template:
Short tagline. Clear value proposition.
How it works:
Brief explanation of the mechanism.
Features:
• Feature 1 — short description
• Feature 2 — short description
• Feature 3 — short description
Privacy-first:
• No tracking
• No accounts
• All data stored locally
Call to action.
Firefox Add-ons
npm run zip:firefox # Creates .output/my-extension-x.x.x-firefox.zip
# Also creates .output/my-extension-x.x.x-sources.zip (required for review)
# Upload to Firefox Add-ons Developer Hub
CRITICAL: Firefox Manifest Requirements (2024+)
Firefox requires browser_specific_settings.gecko.data_collection_permissions for all new extensions:
// wxt.config.ts
export default defineConfig({
manifest: {
// ... other config
browser_specific_settings: {
gecko: {
id: 'your-extension@your-domain.com',
strict_min_version: '142.0', // Required for data_collection_permissions
data_collection_permissions: {
// For extensions that DON'T collect data:
required: ['none'],
// For extensions that DO collect data, specify types:
// required: ['browsingActivity', 'websiteContent'],
// optional: ['locationInfo'],
},
},
},
},
});
Valid data_collection_permissions values:
'none'— extension doesn't collect any data'locationInfo'— physical location'healthInfo'— health data'financialAndPaymentInfo'— payment info'authenticationInfo'— login credentials'personalCommunications'— messages, emails'browsingActivity'— browsing history'websiteContent'— page content'websiteActivity'— clicks, interactions'searchTerms'— search queries'bookmarksInfo'— bookmarks'personallyIdentifyingInfo'— PII
Firefox submission notes template:
Version notes:
Initial release of [Extension Name] - [brief description].
Notes for reviewer:
- No account required to test
- To test:
1. Install extension
2. [Step by step testing instructions]
- No external services or APIs used
- All data stored locally via browser.storage
Edge Add-ons
# Use the same Chrome zip - Edge is Chromium-based
npm run zip # Creates .output/my-extension-x.x.x-chrome.zip
# Upload to Edge Add-ons Developer Dashboard
Naming Convention for ZIPs
# Rename for clarity
mv .output/my-extension-1.0.0-chrome.zip ./my-extension-v1.0.0-chrome.zip
mv .output/my-extension-1.0.0-firefox.zip ./my-extension-v1.0.0-firefox.zip
Security Checklist
- Minimal permissions (request only what's needed)
- No
eval()or inline scripts - Validate all external data
- Use HTTPS only
- No API keys in source code
- Input sanitization in content scripts
- pre-commit hooks with gitleaks
Resources
Converted and distributed by TomeVault — claim your Tome and manage your conversions.