chrome-extension-wxt

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:

Quick Start Workflow

1. Initialize WXT Project

# 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

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)

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

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

// entrypoints/popup/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
ReactDOM.createRoot(document.getElementById('root')!).render(
  
    
  
);

Configuration

Basic wxt.config.ts

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

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

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

// Inject script into page context
import { injectScript } from 'wxt/client';
await injectScript('/injected.js', {
  keepInDom: false,
});

Building & Deployment

Production Build

# 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

# 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

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

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)

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:

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

Bundled Resources

Use these resources as needed when building your extension.

Basic wxt.config.ts

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