Astro

Astro 是一个灵活的元框架，适用于各种工具和集成，使您能够利用众多生态系统。

它还允许您使用您喜欢的 UI 框架（或根本不使用框架）编写组件，并在构建时将页面渲染为静态 HTML，或者在服务器上使用服务器端渲染（SSR）动态渲染。

这样可以得到快速、对 SEO 友好的输出，可以部署到任何静态托管环境或服务器上。

Astro 替代 Qwik City

在将 Astro 与 Qwik 集成时，重要的是要注意 Qwik City 的 API 与 Astro 不兼容。

Astro 是一个元框架，提供了自己的一套用于处理这些问题的 API 和功能。这些包括：

路由
页面
布局
数据获取
服务器端渲染（SSR）

因此，在将 Qwik 与 Astro 集成时，应使用 Astro 的 API 和功能，而不是 Qwik City 的 API。这将确保您的 Qwik 组件在 Astro 环境中正常工作。有关更多信息，请参阅Astro 文档。

@qwikdev/astro 💜

此集成利用了 Resumability 在 Astro 中的强大功能，使用 Qwik 组件。

安装

有两种方法可以添加集成。让我们从最简单的方法开始！

Astro CLI

Astro 提供了一个命令行工具来集成内置的集成：astro add。此命令将：

可选地安装所有必需的依赖项和对等依赖项
可选地修改您的 astro.config.* 文件以应用集成

要安装 @qwikdev/astro，请从项目目录中运行以下命令，并按照提示操作：

# 使用 NPM
npx astro add @qwikdev/astro
 
# 使用 Yarn
yarn astro add @qwikdev/astro
 
# 使用 PNPM
pnpm astro add @qwikdev/astro

设置 TypeScript 配置

集成需要在 tsconfig.json 中添加以下内容，以便 TypeScript 可以识别 Qwik 的 JSX 类型。

"compilerOptions": {
  "jsx": "react-jsx",
  "jsxImportSource": "@builder.io/qwik"
}

如果遇到任何问题，请在 Github 上发布，然后尝试下面的手动安装。

手动安装

首先，像这样安装 @qwikdev/astro 集成：

npm install @qwikdev/astro

通常，软件包管理器会安装对等依赖项。但是，如果在启动 Astro 时收到 Cannot find package '@builder.io/qwik' 警告，请安装 Qwik。

npm install @builder.io/qwik

现在，使用 integrations 属性将集成添加到您的 astro.config.* 文件中：

  // astro.config.mjs
  import { defineConfig } from 'astro/config';
+ import qwikdev from '@qwikdev/astro';
 
  export default defineConfig({
    // ...
    integrations: [qwikdev()],
    //             ^^^^^
  });

Qwik 不进行水合，它是根本不同的

Astro 以其部分水合方法而闻名，而 Qwik 不需要水合。

添加 Qwik 组件

在其他 UI 框架中，需要使用水合指令来实现交互性，例如 client:only 或 client:load。但是在 Qwik 中，这些都不需要，因为没有水合！

在像 Astro 或 Qwik City 这样的元框架中使用 Qwik 时，组件在服务器上加载，以独立线程预取，并在客户端上“恢复”。

例如，这是如何在 Qwik 中创建一个计数器组件（例如在 src/components/counter.tsx 中）。

import { component$, useSignal } from "@builder.io/qwik";
 
export const Counter = component$(() => {
  const counter = useSignal(0);
 
  return <button onClick$={() => counter.value++}>{counter.value}</button>;
});

可以在我们的 index.astro 页面中这样使用它：

    ---
    import { Counter } from "../components/counter";
    ---
 
    <html lang="en">
        <head>
            <meta charset="utf-8" />
            <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
            <meta name="viewport" content="width=device-width" />
            <meta name="generator" content={Astro.generator} />
            <title>Astro</title>
        </head>
        <body>
            <h1>Astro.js - Qwik</h1>
            /* 没有水合指令！ */
            <Counter />
        </body>
    </html>

路线图

Astro 还有一些缺失的功能，我们希望在将来添加。这包括更好的预取和洞察。

如果您认为在 Astro 和 Qwik 中还有其他令人惊叹的功能，请随时尝试一下。

贡献

我们非常欢迎您的贡献！首先阅读我们的贡献指南。其中包含了您参与的所有信息，包括关于集成在内部是如何工作的详细部分。

在 builder.io 的 Discord 中还有一个 qwik-astro 频道，用于讨论 API 更改、集成的可能想法和其他有趣的内容。😊

鸣谢

特别感谢 Astro 核心团队的 Matthew 和 Nate！没有他们的帮助，这个集成是不可能的。

Nate 的联系方式：

Contributors

Thanks to all the contributors who have helped make this documentation better!