@astrojs/ preact

v4.1.0 GitHub npm 变更日志

这个 Astro 集成 为你的 Preact 组件启用了渲染和客户端水合。

为何选择 Preact？

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

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

想在使用此集成之前了解更多关于 Preact 的信息吗？
请查看他们网站上的交互式教程 “学习 Preact”。

安装

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

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

npx astro add preact

pnpm astro add preact

yarn astro add preact

如果你遇到任何问题，请随时在 GitHub 上向我们报告，并尝试下面的手动安装步骤。

手动安装

首先，安装 @astrojs/preact 包

npm install @astrojs/preact

pnpm add @astrojs/preact

yarn add @astrojs/preact

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

npm install preact

pnpm add preact

yarn add preact

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

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

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

并将以下代码添加到 tsconfig.json 文件中。

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact"
  }
}

用法

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

📦 框架组件是如何加载的，
💧 客户端注入选项，以及
🤝 混合和嵌套不同框架的机会

另外，请查看我们的Astro 集成文档以了解更多关于集成的信息。

配置

Astro Preact 集成处理 Preact 组件的渲染方式，并有其自己的选项。在 astro.config.mjs 文件中更改这些选项，这是你项目的集成设置所在之处。

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

compat

你可以启用 preact/compat，这是 Preact 的兼容层，用于渲染 React 组件，而无需安装或将 React 的大型库发送到用户的 Web 浏览器。

为此，请向 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 网站上的“切换到 Preact（从 React）”中阅读更多信息。

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

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

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

devtools

添加于： @astrojs/preact@3.3.0

你可以在开发中通过向你的 preact() 集成配置传递一个带有 devtools: true 的对象来启用 Preact devtools

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

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

选项

组合多个 JSX 框架

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

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

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

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({
  // Enable many frameworks to support all different kinds of components.
  // No `include` is needed if you are only using a single JSX framework!
  integrations: [
    preact({
      include: ['**/preact/*'],
    }),
    react({
      include: ['**/react/*'],
    }),
    solid({
      include: ['**/solid/*'],
    }),
  ],
});