内容
# extensionjs-react-template
**英文** · [简体中文](README.zh-CN.md)
> 一个基于官方 [Extension.js React 模板](https://extension.js.org/docs/getting-started/templates/react) 的React启动器，包含我每个项目都会用到的功能。
## 为什么选择这个模板
官方的Extension.js React模板故意保持最小化。这个分支保留了其结构，并在其上层添加了常用功能，以便于新建的扩展程序可以直接使用文档感知的AI工具和浏览器调试功能，无需逐个项目设置。
## 模板内容
**基准（来自官方模板）**
- React 19 + TypeScript
- **Chromium上的Manifest V3** — 一个MV3服务工作线程后台，`side_panel`侧边栏，以及注入所有页面的内容脚本。
- Chrome / Firefox / Edge 跨浏览器构建
**与官方模板的更改**
- **Firefox上的Manifest V3** — 官方模板将Firefox作为 **Manifest V2** 交付。本分支将其迁移到MV3（Firefox 109+支持MV3和Extension.js构建），因此没有MV2的回退。单个清单仍然根据目标解析：在Firefox上，背景变为事件页面 `background.scripts`，侧边栏变为 `sidebar_action`。
> 发布到Firefox Add-ons（AMO）可能需要稳定的扩展程序ID — 在 [`src/manifest.json`](src/manifest.json) 中添加 `browser_specific_settings.gecko.id` 即可。对于本地开发，这不是必需的。
**添加的集成**
- **AI文档访问** — 托管的Extension.js文档MCP服务器，因此您的编辑器/助手可以从当前文档中回答“如何…”，而非过时的训练数据。参见 [AI访问](https://extension.js.org/docs/ai-access)。
- **Chrome DevTools MCP** — 在Extension.js控制服务器（`@extension.dev/mcp`）旁边运行Google的 `chrome-devtools-mcp`，为AI代理提供原始的Chrome调试功能，以及跨浏览器的扩展程序控制，配置简单。参见 [Chrome DevTools MCP与Extension.js](https://extension.js.org/docs/integrations/chrome-devtools-mcp)。
- **Tailwind CSS** — 通过PostCSS连接的实用优先样式，因此您可以在组件中使用实用类。参见 [样式](#styling) 和 [Tailwind CSS与Extension.js](https://extension.js.org/docs/integrations/tailwindcss)。
- **shadcn/ui** — 可访问的、可以直接复制到项目中的组件，基于Tailwind构建，已经连接好（`components.json`，`@/`路径别名，和 `cn()` 助手），因此您可以将组件放入 `src/components/ui` 并立即使用。参见 [样式](#styling) 和 [shadcn/ui与Extension.js](https://extension.js.org/docs/integrations/shadcnui)。
- **ESLint** — 一个扁平配置（[`eslint.config.ts`](eslint.config.ts)）lint设置，涵盖JS/TS、React、JSON、Markdown和CSS。它通过 `pnpm run lint` 在构建管道之外运行，并附带一个用于 `tsc` 的配套 `pnpm run type-check`。参见 [命令](#commands) 和 [ESLint与Extension.js](https://extension.js.org/docs/integrations/eslint)。
## MCP服务器
上述集成在 [`.mcp.json`](.mcp.json) 中声明，并被Claude Code（和其他指向相同配置的MCP兼容客户端）自动拾取。
| 服务器 | 传输方式 | 它能为助手提供什么 |
| ----------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `extensionjs` | HTTP（托管） | 搜索Extension.js文档并回答当前内容的问题。 |
| `extension-dev` | stdio（`@extension.dev/mcp`） | 跨浏览器的扩展程序控制：开发服务器、热重载、生成的清单、存储和每个上下文的日志。 |
| `chrome-devtools` | stdio（`chrome-devtools-mcp`） | 通过CDP的原始Chrome调试：驱动页面、检查网络/性能，以及扩展程序工具。 |
> `chrome-devtools`服务器配置为 `--browser-url=http://127.0.0.1:9222`，因此它附加到已经在该远程调试端口监听的Chrome实例。在使用这些工具之前，请启动这样的浏览器。
一个经验法则：如果你要处理 **项目**（源代码、构建、清单、重载），请选择 `extension-dev`；如果你要处理 **浏览器**（页面、网络、性能），请选择 `chrome-devtools`。
## 样式
### Tailwind CSS
[Tailwind CSS](https://tailwindcss.com) v4 通过PostCSS连接：
- [`postcss.config.mjs`](postcss.config.mjs) 注册了 `@tailwindcss/postcss` 插件。
- [`src/styles/globals.css`](src/styles/globals.css) 引入了Tailwind并定义了主题。
从入口点导入 `globals.css`（侧边栏已经这样做了），然后在组件中使用实用类。参见 [Tailwind CSS与Extension.js](https://extension.js.org/docs/integrations/tailwindcss) 获取详细信息。
### shadcn/ui
[shadcn/ui](https://ui.shadcn.com) 建立在Tailwind之上，允许您将可访问的组件直接拉入您自己的源代码树中。连接已经就绪：
- [`components.json`](components.json) — shadcn CLI的配置（样式、基准颜色、`@/`别名、Lucide图标）。
- [`tsconfig.json`](tsconfig.json) 将 `@/*` 别名映射到 `src/*`，生成的组件从此处导入。
- [`src/lib/utils.ts`](src/lib/utils.ts) 导出用于合并类名的 `cn()` 助手。
- [`src/styles/globals.css`](src/styles/globals.css) 导入 `shadcn/tailwind.css` 和 `tw-animate-css`，并定义浅色/深色设计令牌（CSS变量）。
使用shadcn CLI添加组件，它们将位于 `src/components/ui`：
```bash
pnpm dlx shadcn@latest add button
```
然后通过 `@/` 别名导入它们：
```tsx
import {Button} from '@/components/ui/button'
```
参见 [shadcn/ui与Extension.js](https://extension.js.org/docs/integrations/shadcnui) 获取详细信息。
## 命令
### dev
在开发模式下运行扩展程序。针对具有 `--browser` 的浏览器：
```bash
pnpm run dev # Chromium（默认）
pnpm run dev -- --browser=firefox
pnpm run dev -- --browser=edge
```
### build
为生产环境构建。便捷脚本针对每个浏览器：
```bash
pnpm run build # Chrome（默认）
pnpm run build:firefox
pnpm run build:edge
```
### preview
在浏览器中预览生产构建：
```bash
pnpm run preview
```
### lint
使用ESLint检查代码质量，并使用 `tsc` 单独进行类型检查：
```bash
pnpm run lint
pnpm run type-check
```
## 了解更多
- [Extension.js 文档](https://extension.js.org)
- [React 模板](https://extension.js.org/docs/getting-started/templates/react)
