Astro

Astro - это гибкий мета-фреймворк, который позволяет использовать широкий спектр инструментов и интеграций, что дает возможность задействовать многочисленные экосистемы.

Он также позволяет писать компоненты, используя ваш любимый UI-фреймворк (или вообще без него), и рендерит ваши страницы в статический HTML во время сборки или динамически на сервере с помощью Server-Side Rendering (SSR).

В результате получается быстрый, дружественный для SEO результат, который может быть развёрнут на любом статическом хостинге или сервере.

Astro вместо Qwik City

При интеграции Astro с Qwik важно учитывать, что API Qwik City не совместим с Astro.

Astro - это метафреймворк, предоставляющий собственный набор API и функций для решения задач, к которым относятся:

маршрутизация
страницы
макеты
получение данных
рендеринг на стороне сервера (SSR)

Поэтому при интеграции Qwik с Astro следует использовать API и возможности Astro, а не API Qwik City. Это обеспечит корректную работу компонентов Qwik в среде Astro. Более подробная информация приведена в документации Astro.

@qwikdev/astro 💜

Эта интеграция позволяет использовать возможность Возобновляемости внутри Astro, используя компоненты Qwik.

Установка

Существует два метода добавления интеграции. Начнем с самого простого!

Astro CLI

Astro поставляется с инструментом командной строки для включения встроенных интеграций: astro add. Эта команда позволит:

Опционально установить все необходимые зависимости и peer-зависимости
Опционально изменит ваш файл 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 распознавал JSX-типы Qwik.

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

Если у вас возникнут какие-либо проблемы, пожалуйста, опубликуйте их на Github и попробуйте выполнить ручную установку, описанную ниже.

Ручная установка

Сначала установите интеграцию @qwikdev/astro следующим образом:

npm install @qwikdev/astro

Как правило, менеджеры пакетов устанавливают peer-зависимости. Однако, если при запуске Astro выдается предупреждение Cannot find package '@builder.io/qwik', установите Qwik.

npm install @builder.io/qwik

Теперь добавьте интеграцию в файл astro.config.*, используя секцию integrations в конфигурации:

  // 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 они не нужны, так как нет гидратации!

При использовании Qwik внутри мета-фреймворка, например Astro или Qwik City, компоненты загружаются на сервере, предварительно загружаются в отдельном потоке и "возобновляются" на клиенте.

Например, вот как мы создаем компонент счетчика в 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 отсутствуют некоторые вещи, которые мы хотели бы добавить в будущем. Это улучшенная предварительная загрузка и Insights.

Если вы считаете, что с Astro & Qwik можно сделать что-то ещё, не стесняйтесь, попробуйте.

Вклад

Мы будем рады, если вы внесёте свой вклад! Начните с прочтения нашего Руководства. В нём содержится вся информация, необходимая для участия в проекте, включая подробный раздел о том, как работает интеграция под капотом.

Также существует канал qwik-astro в дискорде builder.io для обсуждения изменений в API, возможных идей по интеграции и других интересных вещей. 😊

Благодарности

Особая благодарность Matthew и Nate из основной команды Astro! Без их помощи эта интеграция была бы невозможна.

Контакты Nate:

Участники

Спасибо всем участникам, которые помогли сделать эту документацию лучше!