Настройка Astro и островов React

Создание начального проекта Astro выполняется с помощью npx create astro@latest, которое запускает интерактивный мастер для выбора шаблона, настроек TypeScript и менеджера пакетов. Astro поддерживает несколько стартовых вариантов, включая пустой шаблон, шаблон блога и шаблоны документации.

Интеграции Astro добавляют в проект поддержку фреймворков. Запуск npx astro add react автоматически устанавливает @astrojs/react, react и react-dom, а также обновляет astro.config.mjs, добавляя интеграцию React. Для всей настройки требуется всего одна команда.

Файл .astro — это формат компонентов Astro. Он состоит из секции метаданных (JavaScript между разделителями ---) и секции шаблона. По умолчанию файл Astro выводит статический HTML — JavaScript не отправляется в браузер, если явно не добавить директиву клиента.

Импорт компонента React в файл Astro выполняется с помощью стандартного синтаксиса модулей ES: import Counter from './Counter.jsx'. Без директивы клиента Astro отображает компонент React на сервере в виде статического HTML и отправляет этот HTML в браузер — для компонента не поставляется JavaScript.

Добавление client:visible к тегу компонента в шаблоне Astro превращает его в остров: <Counter client:visible />. Теперь Astro поставляет JavaScript Counter, гидратирует его при прокрутке до области просмотра и делает его интерактивным. Без директивы это статический HTML.

Компоненты React, используемые как острова Astro, пишутся на обычном React — в них можно использовать хуки, состояние, эффекты и любые библиотеки React. В самом компоненте React нет специального API Astro. Граница острова определяется в шаблоне Astro, а не внутри кода компонента.

Каждый экземпляр острова представляет собой независимое дерево React. Два острова Counter на одной странице не используют общее состояние. Если Вам нужно общее состояние, есть три варианта: объединить их в один остров, использовать параметры поиска в URL для сериализуемого состояния или воспользоваться библиотекой общего состояния, например nanostores.

Библиотека @nanostores/react предоставляет легковесные атомы, на которые может подписаться любой остров. Один остров записывает значение в атом хранилища nanostores, а другой считывает его. Поскольку хранилища nanostores не зависят от фреймворка, этот подход также работает между островами React и Vue на одной странице.

Коллекции содержимого Astro предоставляют типобезопасный способ управления файлами Markdown и MDX. Определите схему коллекции с помощью Zod, поместите файлы Markdown в src/content/, и Astro сгенерирует полностью типизированные функции запросов. Это стандартный подход для записей блога, документации и страниц продуктов.

Запуск astro build создает папку dist/ со статическими файлами HTML. Для каждой страницы Astro выводит файл HTML с содержимым, отрендеренным на сервере, и только те пакеты JavaScript, которые нужны островам на этой странице. Страницы без островов не содержат JavaScript.

Статический результат можно развернуть в любой CDN (Netlify, Vercel, Cloudflare Pages) без сервера. Если требуется серверный рендеринг (динамические маршруты, конечные точки API), Astro поддерживает адаптеры SSR для Node.js, Vercel Edge, Cloudflare Workers и Deno. Острова работают одинаково в обоих режимах.

Какое минимальное изменение нужно внести в импортированный компонент React в шаблоне Astro, чтобы сделать его интерактивным на клиенте?

Настройте Astro с React с помощью npx astro add react. Файлы Astro по умолчанию статичны; добавление директивы client: к тегу компонента React превращает его в гидратируемый остров. Компоненты React являются обычными компонентами React и не используют специальные API Astro. Состояние изолировано для каждого острова, а nanostores обеспечивает связь между островами. При сборке создается статический HTML только с тем JavaScript островов, который необходим.