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(<App />);
      },
    });

    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(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

html

<!-- entrypoints/popup/index.html -->
<!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

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<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

typescript

// utils/messaging.ts
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

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:

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

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.

chrome-extension-wxt

NPX Install

Tags

SKILL.md Content

Chrome Extension Development with WXT

When to Use This Skill

Quick Start Workflow

1. Initialize WXT Project

2. Project Structure

3. Development Commands

Core Entry Points

Background Script (Service Worker)

Content Script

Popup UI

Configuration

Basic wxt.config.ts

Common Patterns

Type-Safe Storage

Type-Safe Messaging

Script Injection

Building & Deployment

Production Build

Multi-Browser Build

Modern Stacks (2025)

WXT + React + Tailwind + shadcn/ui

WXT + React + Mantine UI

WXT + React + TypeScript (Minimal)

Advanced Topics

Troubleshooting

Resources

Official Documentation

Bundled Resources