Agent skill

chrome-extension-wxt

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.

View SKILL.md on GitHub Repository
Stars 19
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/tenequm/skills/tree/main/skills/chrome-extension-wxt

Metadata

Additional technical details for this skill

version
1.1.0

SKILL.md

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:

  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

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

tenequm/skills

command-skill-creator

Create automation command skills (slash commands) for Claude Code projects. Use when building `/slash-commands` that automate multi-step workflows - deploys, commits, releases, migrations, cross-repo operations, or any repeatable process. Triggers on "create a command", "make a slash command", "automate this workflow", "turn this into a command", "build a command skill", or when designing phased execution skills with approval gates. For command-type skills (imperative prompts in `.claude/skills/`), NOT knowledge/reference skills.

19 0
Explore
tenequm/skills

openclaw-ref

OpenClaw platform reference - plugin system, extensions, configuration, boot/provisioning, channels, models, CLI. Use when working on openclaw codebase, building openclaw plugins/extensions, configuring openclaw instances, provisioning openclaw gateways, designing agent provisioning flows (e.g. agentbox), or debugging openclaw config/plugin/channel issues. Triggers on openclaw, openclaw config, openclaw plugin, openclaw extension, openclaw channel, openclaw gateway, openclaw provisioning, openclaw onboarding, openclaw boot, openclaw skills, BOOT.md, openclaw.plugin.json, openclaw-x402, agentbox provisioning.

19 0
Explore
tenequm/skills

vite

Configure and optimize Vite 7 for React projects. Covers build tooling, dev server, plugins, HMR, chunk splitting, Environment API, and Rolldown integration. Use when setting up Vite, configuring builds, optimizing bundles, managing plugins, or troubleshooting dev server. Triggers on vite, vite config, vite plugin, HMR, dev server, build optimization, chunk splitting, rolldown, vite proxy, environment api, rolldown-vite.

19 0
Explore
tenequm/skills

biome

Lint and format frontend code with Biome 2.4. Covers type-aware linting, GritQL custom rules, domains, import organizer, and migration from ESLint/Prettier. Use when configuring linting rules, formatting code, writing custom lint rules, or setting up CI checks. Triggers on biome, biome config, biome lint, biome format, biome check, biome ci, gritql, migrate from eslint, migrate from prettier, import sorting, code formatting, lint rules, type-aware linting, noFloatingPromises.

19 0
Explore
tenequm/skills

solana-development

Build Solana programs with Anchor framework or native Rust. Use when developing Solana smart contracts, implementing token operations, testing programs, deploying to networks, or working with Solana development. Covers both high-level Anchor framework (recommended) and low-level native Rust for advanced use cases.

19 0
Explore
tenequm/skills

gh-cli

GitHub CLI for remote repository analysis, file fetching, codebase comparison, and discovering trending code/repos. Use when analyzing repos without cloning, comparing codebases, or searching for popular GitHub projects.

19 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results