在浏览器扩展中使用 React

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

什么场景适合用 React

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

模板示例

`new-react`

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

npx extension@latest create my-extension --template=newtab-react

pnpx extension@latest create my-extension --template=newtab-react

yarn dlx extension@latest create my-extension --template=newtab-react

bunx extension@latest create my-extension --template=newtab-react

deno run -A npm:extension@latest create my-extension --template=newtab-react

仓库：extension-js/examples/newtab-react

`content-react`

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

npx extension@latest create my-extension --template=content-react

pnpx extension@latest create my-extension --template=content-react

yarn dlx extension@latest create my-extension --template=content-react

bunx extension@latest create my-extension --template=content-react

deno run -A npm:extension@latest create my-extension --template=content-react

仓库：extension-js/examples/content-react

`new-react-router`

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

npx extension@latest create my-extension --template=newtab-react-router

pnpx extension@latest create my-extension --template=newtab-react-router

yarn dlx extension@latest create my-extension --template=newtab-react-router

bunx extension@latest create my-extension --template=newtab-react-router

deno run -A npm:extension@latest create my-extension --template=newtab-react-router

仓库：extension-js/examples/newtab-react-router

在现有扩展中使用

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

安装

安装 React 运行时依赖：

npm install react react-dom

pnpm add react react-dom

yarn add react react-dom

bun add react react-dom

deno add npm:react npm:react-dom

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

npm install -D @types/react @types/react-dom

pnpm add -D @types/react @types/react-dom

yarn add -D @types/react @types/react-dom

bun add -d @types/react @types/react-dom

deno add -D npm:@types/react npm:@types/react-dom

React 集成还会用到一些可选包，例如 react-refresh 和 @rspack/plugin-react-refresh。两者都作为 extension-develop 的依赖一起发布，所以一次正常的安装已经能解析到它们。当其中一个无法被解析时，构建无法启动，错误信息会指出需要安装哪些包。错误里的安装命令会按你项目使用的包管理器来书写。

配置

常见的 React 文件名模式：

JavaScript：*.jsx
TypeScript：*.tsx

开发期行为

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

Extension.js 使用 react-refresh 和 @rspack/plugin-react-refresh 来提供 refresh 行为。
如果这些 refresh 包无法从你的项目或 extension-develop 中解析到，构建将无法启动，并打印相应的安装命令。Extension.js 不会替你安装它们，也不会要求你重启。
Extension.js 会应用 React 相关的别名，以确保打包结果里只有一份 React/runtime 实例。

用法示例

在新标签页扩展中

页面入口示例：

<!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>

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>,
);

export default function App() {
  return <h1>Hello, Extension!</h1>;
}

在 `content_script` 文件中

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

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 />);

下一步

当你需要一个侧边栏面板加上一个 content script 时，从 React 模板（--template=react）开始。
进一步了解 TypeScript 支持。
了解 Extension.js 如何处理 Sass 模块。

Introduction

Browser extension fundamentals

Getting started

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

在浏览器扩展中使用 React

什么场景适合用 React

模板示例

`new-react`

`content-react`

`new-react-router`

在现有扩展中使用

安装

配置

开发期行为

用法示例

在新标签页扩展中

在 `content_script` 文件中

下一步

视频讲解

模板演示

​什么场景适合用 React

​模板示例

​new-react

​content-react

​new-react-router

​在现有扩展中使用

​安装

​配置

​开发期行为

​用法示例

​在新标签页扩展中

​在 content_script 文件中

​下一步

​视频讲解

​模板演示

什么场景适合用 React

模板示例

`new-react`

`content-react`

`new-react-router`

在现有扩展中使用

安装

配置

开发期行为

用法示例

在新标签页扩展中

在 `content_script` 文件中

下一步

视频讲解

模板演示