@astrojs/ preact

v3.0.1 GitHub npm Changelog

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

为什么选择 Preact?

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

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

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

安装

快速安装

astro add 命令行工具可以自动化为你安装。在新的终端窗口中运行以下命令之一。（如果你不确定你正在使用哪个包管理器，运行第一个命令。）然后，按照提示操作，在终端中输入“y”（表示 “yes”）来确认每一个步骤。

# 使用 NPM
npx astro add preact
# 使用 Yarn
yarn astro add preact
# 使用 PNPM
pnpm astro add preact

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

手动安装

首先，使用你的包管理器安装 @astrojs/preact包。如果你使用的是 npm 或者不确定，可以在终端中运行以下命令：

npm install @astrojs/preact

大多数包管理器会一并安装相关的 peer 依赖。然而，如果在启动 Astro 时看到”找不到包 preact “（或类似）的警告，你将需要安装 Preact：

npm install preact

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

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。

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 来实现。

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

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

选项

组合多个 JSX 框架

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

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

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

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/*'],
    }),
  ],
});