Chrome Extension React Starter

基于 React + TypeScript + Vite 的 Chrome MV3 扩展脚手架，包含所有核心扩展组件及完整的组件间通信示例。

1. 技术栈

类别	技术
框架	React 19 + TypeScript 6
构建	Vite 8 + @crxjs/vite-plugin
状态管理	Zustand + TanStack Query
路由	React Router 7 (HashRouter)
Hooks	ahooks
UI	Tailwind CSS v4 + shadcn/ui
代码规范	Biome
包管理	pnpm

2. 扩展组件

组件	路径	说明
Background Service Worker	src/background/	消息总线、DNR 规则管理
Content Script	src/content/	注入页面，Shadow DOM 样式隔离
Popup	src/popup/	Toolbar Action，TanStack Query 示例
Side Panel	src/sidepanel/	实时接收 Content Script 数据
Options Page	src/options/	React Router 路由，设置持久化

3. 快速开始

# 安装依赖
pnpm install

# 开发构建（监听模式）
pnpm dev

# 生产构建
pnpm build

# 代码检查
pnpm lint

4. 加载扩展

1. 运行 pnpm build，生成 dist/ 目录
2. 打开 Chrome，访问 chrome://extensions/
3. 开启右上角「开发者模式」
4. 点击「加载已解压的扩展程序」，选择 dist/ 目录

5. 通信链路示例

Content Script
    ↓ sendMessage(PAGE_DATA)
Background Service Worker
    ↓ chrome.runtime.sendMessage (broadcast)
Side Panel (实时显示)

Popup
    ↓ sendMessage(GET_TAB_INFO)
Background Service Worker
    ↓ return { tabId, url, title }
Popup (TanStack Query 展示)

6. 目录结构

src/
├── background/          # Service Worker
│   ├── index.ts         # 主入口
│   ├── message-handler.ts
│   └── dnr-handler.ts
├── content/             # Content Script
│   ├── index.tsx        # Shadow DOM 注入
│   └── ContentApp.tsx
├── popup/               # Toolbar Popup
├── sidepanel/           # Side Panel
├── options/             # Options Page (React Router)
│   └── pages/
├── components/ui/       # shadcn/ui 组件
├── hooks/               # 自定义 Hooks
├── store/               # Zustand Stores
├── lib/
│   ├── chrome/          # Chrome API 封装
│   └── query-client.ts
└── types/               # 类型定义

7. 环境变量

复制 .env.example 为 .env.local 并按需修改：

cp .env.example .env.local