Question

这个 Astro 集成 可以为你的 Preact 组件提供服务器端渲染和客户端水合（hydration）功能。

为什么选择 Preact?

Preact 是一个允许你构建适用于网络的交互式 UI 组件的库。如果你想使用 JavaScript 在你的网站上构建交互式功能，你可能更喜欢使用它的组件格式，而不是直接使用浏览器的 API。

如果你之前使用过 React，Preact 也是一个很好的选择。Preact 提供与 React 相同的 API，但打包体积更小，仅为 3kB。它甚至支持通过 compat 配置选项来渲染许多 React 组件（见下文）。

在使用这个集成之前，想要了解更多关于 Preact 的信息吗？
可以查看他们网站上的 “在 10 分钟内学习 Preact” 互动教程。

安装

Astro 包含了一个 astro add 命令，用于自动设置官方集成。如果你愿意，可以改为手动安装集成。

要安装 @astrojs/preact，请在你的项目目录中运行以下命令并按照提示操作：

• npm
• pnpm
• Yarn

npx astro add preact

pnpm astro add preact

yarn astro add preact

如果遇到任何问题，请随时在 GitHub 留言 并尝试以下的手动安装步骤。

手动安装

首先，安装 @astrojs/preact 包:

• npm
• pnpm
• Yarn

npm install @astrojs/preact

pnpm add @astrojs/preact

yarn add @astrojs/preact

大多数包管理器也会安装相关的对等依赖。如果在启动 Astro 时看到 “Cannot find package ‘preact’“（或类似）的警告，你需要安装 Preact：

• npm
• pnpm
• Yarn

npm install preact

pnpm add preact

yarn add preact

然后，使用 integrations 属性将此集成应用到你的 astro.config.* 文件中：

astro.config.mjs

import { defineConfig } from 'astro/config';import preact from '@astrojs/preact';


export default defineConfig({
  // ...
  integrations: [preact()],
});

使用

要在 Astro 中使用你的第一个 Preact 组件，请前往我们的 UI 框架文档。你将会了解到：

• 如何加载框架组件
• 客户端水合选项
• 将不同框架混合和嵌套在一起的机会

还可以查阅我们的 Astro 集成文档 以获取更多关于集成的信息。

配置

Astro Preact 集成处理了 Preact 组件的渲染，并具有自己的选项。你可以在 astro.config.mjs 文件中修改这些选项，这是你的项目集成设置所在的地方。

对于基本用法，你无需配置 Preact 集成。

兼容

你可以启用 preact/compat，这是 Preact 的兼容层，用于在不需要安装或将 React 的较大库发送到用户的网络浏览器的情况下渲染 React 组件。

要实现这一点，向 Preact 集成传递一个对象，并设置 compat: true。

astro.config.mjs

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';


export default defineConfig({
  integrations: [preact({ compat: true })],
});

当启用了 compat 选项后，Preact 集成将会在你的项目中渲染 React 组件和 Preact 组件，同时还允许你在 Preact 组件中导入 React 组件。在 Preact 网站的“从 React 切换到 Preact”页面中可以阅读更多信息。

当导入 React 组件库时，为了将 react 和 react-dom 的依赖替换为 preact/compat, 你可以使 overrides 来实现。

package.json

{
  "overrides": {
    "react": "npm:@preact/compat@latest",
    "react-dom": "npm:@preact/compat@latest"
  }
}

可以查阅pnpm overrides 和 yarn resolutions 的文档，了解它们各自的覆盖功能。

注意

目前，compat 选项只适用于 React 库，将代码以 ESM 的形式导出。如果在构建时出现错误，请尝试将该库添加到你的vite.ssr.noExternal: ['the-react-library'] 的 astro.config.mjs 文件中。

开发者工具

添加于： @astrojs/preact@3.3.0 新

你可以通过在开发中向你的 preact() 集成配置传递一个包含 devtools: true 的对象来启用 Preact 开发者工具：

astro.config.mjs

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';


export default defineConfig({
  // ...
  integrations: [preact({ devtools: true })],
});

选项

组合多个 JSX 框架

当你在同一个项目中使用多个 JSX 框架（React、Preact、Solid）时，Astro 需要确定每个组件应该使用哪个 JSX 框架的转换器（transformation）。如果你只向你的项目中添加了一个 JSX 框架集成，那么就不需要额外的配置。

使用 include（必填）和 exclude（可选）配置选项来指定哪些文件属于哪个框架。为你使用的每个框架提供一个文件或/和文件夹数组。通配符可用于包含多个文件路径。

我们建议将每个框架的组件放在同一个文件夹中（例如 /components/react/ 和 /components/solid/），以便更容易地指定你的包含内容，但这不是必需的：

astro.config.mjs

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';


export default defineConfig({
  // 启用多个框架来支持所有不同类型的组件。
  // 如果你只使用一个 JSX 框架，则不需要 `include`！
  integrations: [
    preact({
      include: ['**/preact/*'],
    }),
    react({
      include: ['**/react/*'],
    }),
    solid({
      include: ['**/solid/*'],
    }),
  ],
});

示例

• 在 Astro Preact 示例 中展示了如何在 Astro 项目中使用交互式的 Preact 组件。
• 在 Astro Nanostores 示例 中展示了如何在 Astro 项目中在不同组件之间共享状态，甚至可以跨不同框架共享状态。

更多集成

UI 框架

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR 适配器

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

其他集成

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind

Recipes