chrome-extension-wxt — chrome-扩展-wxt

Chrome 扩展 Development with WXT

Build modern, cross-browser 扩展s using WXT - the next-generation 框架 that supports Chrome, Firefox, Edge, Safari, and all Chromium browsers with a single codebase.

When to Use This 技能

Use this 技能 when:

Creating a new Chrome/browser 扩展 设置ting up WXT development 环境 Building 扩展 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 扩展s Quick 启动 工作流

• 初始化 WXT Project

# 创建 new project with 框架 of choice npm 创建 wxt@latest

# Or with specific template npm 创建 wxt@latest -- --template react-ts npm 创建 wxt@latest -- --template vue-ts npm 创建 wxt@latest -- --template svelte-ts

• Project Structure

WXT uses file-based conventions:

project/ ├── entrypoints/ # Auto-discovered entry points │ ├── background.ts # 服务 worker │ ├── content.ts # Content script │ ├── popup.html # Popup UI │ └── options.html # Options page ├── 组件s/ # Auto-导入ed UI 组件s ├── utils/ # Auto-导入ed utilities ├── public/ # Static as设置s │ └── icon/ # 扩展 icons ├── wxt.config.ts # Configuration └── package.json

• Development Commands

npm 运行 dev # 启动 dev server with HMR npm 运行 build # Production build npm 运行 zip # Package for store submission

Core Entry Points

WXT recognizes entry points by filename in entrypoints/ directory:

Background Script (服务 Worker) // entrypoints/background.ts 导出 default defineBackground({ type: '模块', persistent: false,

mAIn() { // 列出en for 扩展 事件 browser.action.on命令行工具cked.添加列出ener((tab) => { console.记录('扩展 命令行工具cked', tab); });

// Handle messages browser.运行time.onMessage.添加列出ener((message, 发送er, 发送响应) => { // Handle message 发送响应({ 成功: true }); return true; // Keep channel open for a同步 }); }, });

Content Script // entrypoints/content.ts 导出 default defineContentScript({ matches: ['://.example.com/'], 运行At: 'document_end',

mAIn(ctx) { // Content script 记录ic console.记录('Content script loaded');

// 创建 UI const ui = 创建ShadowRootUi(ctx, { name: 'my-扩展-ui', position: 'inline', anchor: 'body',

onMount(contAIner) { // Mount React/Vue 组件 const root = ReactDOM.创建Root(contAIner); root.render(<应用 />); }, });

ui.mount(); }, });

Popup UI // entrypoints/popup/mAIn.tsx 导入 React from 'react'; 导入 ReactDOM from 'react-dom/命令行工具ent'; 导入 应用 from './应用';

ReactDOM.创建Root(document.获取ElementById('root')!).render( <应用 /> );

Configuration Basic wxt.config.ts 导入 { defineConfig } from 'wxt';

导出 default defineConfig({ // 框架 integration 模块s: ['@wxt-dev/模块-react'],

// Manifest configuration manifest: { name: 'My 扩展', description: '扩展 description', 权限s: ['storage', 'activeTab'], host_权限s: ['://example.com/*'], },

// Browser tar获取 browser: 'chrome', // or 'firefox', 'edge', 'safari' });

Common Patterns Type-Safe Storage // utils/storage.ts 导入 { storage } from 'wxt/storage';

导出 const storage辅助工具 = { a同步 获取(key: string): Promise { return awAIt storage.获取Item(local:${key}); },

a同步 设置(key: string, value: T): Promise { awAIt storage.设置Item(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 { '获取-data': { 请求: { key: string }; 响应: { value: any }; }; }

导出 a同步 function 发送Message( type: K, payload: Messages[K]['请求'] ): Promise { return awAIt browser.运行time.发送Message({ type, payload }); }

Script Injection // Inject script into page 上下文 导入 { injectScript } from 'wxt/命令行工具ent';

awAIt injectScript('/injected.js', { keepInDom: false, });

Building & 部署ment Production Build # Build for specific browser npm 运行 build -- --browser=chrome npm 运行 build -- --browser=firefox

# 创建 store-ready ZIP npm 运行 zip npm 运行 zip -- --browser=firefox

Multi-Browser Build # Build for all browsers npm 运行 zip:all

输出: .输出/my-extens