> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 在浏览器扩展中使用 React

> 用 Extension.js 构建基于 React 的浏览器扩展 UI。自动配置 JSX 转换、别名和开发期 fast refresh。

Extension.js 会从项目依赖中检测 React，并自动配置 JSX/TSX 转换、React 模块别名以及开发期的 fast-refresh 支持。

## 什么场景适合用 React

* 你在构建 popup、options、sidebar 或新标签页这类组件丰富的 UI 界面。
* 你希望在扩展页面与 content script UI 挂载之间复用组件。
* 你已经在 web 项目里使用 React，希望在扩展中沿用同样的开发模式。

## 模板示例

### `new-react`

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/new-react/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=f117edc4f887e1571c03cdc4eeedebd3" alt="new-react template screenshot" width="2400" height="1800" data-path="images/examples/new-react/screenshot.png" />

用一个开箱即用的项目结构搭建 React 新标签页体验。

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=new-react
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=new-react
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest create my-extension --template=new-react
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=new-react
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=new-react
  ```
</CodeGroup>

仓库：[extension-js/examples/new-react](https://github.com/extension-js/examples/tree/main/examples/new-react)

### `content-react`

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/content-react/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=a0b8694d3a7dfdbb38944a1a7c183c58" alt="content-react template screenshot" width="2400" height="1800" data-path="images/examples/content-react/screenshot.png" />

通过 content script 优先的设置，把 React UI 注入现有页面。

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=content-react
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=content-react
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest create my-extension --template=content-react
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=content-react
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=content-react
  ```
</CodeGroup>

仓库：[extension-js/examples/content-react](https://github.com/extension-js/examples/tree/main/examples/content-react)

### `new-react-router`

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/new-react-router/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=58583c4dd35f487acddc923c4214773a" alt="new-react-router template screenshot" width="2400" height="1800" data-path="images/examples/new-react-router/screenshot.png" />

使用 React Router 的客户端路由的 React 扩展。

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=new-react-router
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=new-react-router
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest create my-extension --template=new-react-router
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=new-react-router
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=new-react-router
  ```
</CodeGroup>

仓库：[extension-js/examples/new-react-router](https://github.com/extension-js/examples/tree/main/examples/new-react-router)

## 在现有扩展中使用

按下面的步骤把 React 添加到现有扩展。

### 安装

安装 React 运行时依赖：

<PackageManagerTabs command="install react react-dom" />

如果使用 TypeScript，再安装 React 类型包：

<PackageManagerTabs command="install -D @types/react @types/react-dom" />

### 配置

常见的 React 文件名模式：

* JavaScript：`*.jsx`
* TypeScript：`*.tsx`

## 开发期行为

在开发模式下，当 Extension.js 检测到 React 时，会启用 React refresh 集成。

* Extension.js 使用 `react-refresh` 和 `@rspack/plugin-react-refresh` 来提供 refresh 行为。
* 如果项目缺少可选的 refresh 依赖，Extension.js 会安装它们并请求你重启。
* Extension.js 会应用 React 相关的别名，以确保打包结果里只有一份 React/runtime 实例。

## 用法示例

### 在新标签页扩展中

页面入口示例：

```html theme={null}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>New Extension</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this extension.</noscript>
    <div id="root"></div>
  </body>
  <script src="./index.tsx"></script>
</html>
```

```tsx theme={null}
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

const root = ReactDOM.createRoot(document.getElementById("root"));

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);
```

```tsx theme={null}
export default function App() {
  return <h1>Hello, Extension!</h1>;
}
```

### 在 `content_script` 文件中

对于 content script，把 React 渲染到一个注入的根元素里：

```tsx theme={null}
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./content.css";

const rootDiv = document.createElement("div");
rootDiv.id = "extension-root";
document.body.appendChild(rootDiv);

const root = ReactDOM.createRoot(rootDiv);
root.render(<App />);
```

## 下一步

* 进一步了解 [TypeScript 支持](/docs/languages-and-frameworks/typescript)。
* 了解 Extension.js 如何处理 [Sass 模块](/docs/languages-and-frameworks/sass)。

## 视频讲解