在浏览器扩展中使用 Preact

在保持类 React 开发体验和快速本地迭代的前提下，让扩展 UI 的包体积更小。 Extension.js 会从依赖中检测 Preact，自动配置 JSX/TSX 转换和 React 兼容别名。你写的 React 导入会通过这些别名映射到 Preact。在开发期，改动通过 live reload 生效：受影响的界面会重新加载，而不是就地热替换组件。

什么场景适合用 Preact

你想缩减 popup/sidebar/新标签页等界面的 UI 包体积。
你喜欢 React 风格的组件，但希望运行时更轻。
你在优化低端设备上扩展的启动时间和 UI 响应速度。

模板示例

`new-preact`

用 Preact 和兼容 React 的写法，构建一个更轻的新标签页 UI。

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

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

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

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

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

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

`content-preact`

通过 content script 把一份精巧的 Preact UI 注入到页面内容里。

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

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

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

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

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

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

在现有扩展中使用

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

安装

安装所需依赖：

npm install preact

pnpm add preact

yarn add preact

bun add preact

deno add npm:preact

Preact 自带 TypeScript 类型，所以你不需要单独安装 @types/preact。你只需要添加 preact 这一个包。Extension.js 会从你的项目里解析 preact/compat、preact/test-utils 以及 JSX 运行时，并按找到的内容构建别名映射，所以不需要再额外安装其他包。

配置

Extension.js 期望 Preact 文件使用以下扩展名：

未启用 TypeScript：*.jsx
启用 TypeScript：*.tsx

开发期行为

当 Extension.js 检测到 Preact 时，它会配置：

兼容别名（例如把 react 指向 preact/compat）。
适配 Preact 的 JSX 处理。
开发期的 live reload：文件变化时，受影响的界面会重新加载并重新挂载。

和 React 不同，Preact 目前还享受不到 fast refresh（保留状态的热更新）。上游的 @rspack/plugin-preact-refresh 运行时与 Extension.js 内置的 Rspack 版本不兼容，所以 Extension.js 选择禁用它，而不是让 dev 模式出问题。你的应用在每次编辑后仍然会更新，只是组件状态不会在编辑之间保留。等上游插件修好后，fast refresh 会回归。

排查

编辑后组件状态被重置： 这是目前的预期行为，因为 Preact 用的是 live reload，而不是 fast refresh（见上文）。
未检测到 Preact 集成： 确认 preact 出现在 dependencies 或 devDependencies 中。

用法示例

在新标签页扩展中

要在新标签页扩展中使用 Preact，请把入口作为 <script> 引入 HTML 文件：

<!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 { h, render } from "preact";
import App from "./App";

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

render(<App />, root);

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

在 `content_script` 文件中

对于 content script，创建一个 HTML 元素并把 Preact 渲染进去：

import { h, render } from "preact";
import App from "./App";
import "./content.css";

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

render(<App />, rootDiv);

下一步

进一步了解 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

在浏览器扩展中使用 Preact

什么场景适合用 Preact

模板示例

`new-preact`

`content-preact`

在现有扩展中使用

安装

配置

开发期行为

排查

用法示例

在新标签页扩展中

在 `content_script` 文件中

下一步

视频讲解

模板演示

​什么场景适合用 Preact

​模板示例

​new-preact

​content-preact

​在现有扩展中使用

​安装

​配置

​开发期行为

​排查

​用法示例

​在新标签页扩展中

​在 content_script 文件中

​下一步

​视频讲解

​模板演示

什么场景适合用 Preact

模板示例

`new-preact`

`content-preact`

在现有扩展中使用

安装

配置

开发期行为

排查

用法示例

在新标签页扩展中

在 `content_script` 文件中

下一步

视频讲解

模板演示