7. Client Directives

Client Directives — это специальные атрибуты, контролирующие когда и как интерактивные компоненты (Islands) гидратируются на клиенте. Без директивы Astro рендерит компонент только как статический HTML — без JavaScript.

Что такое гидратация?

Гидратация — процесс превращения статического HTML в интерактивный UI путём подключения JavaScript. В Astro это происходит явно и только там, где нужно.

<!-- Без директивы — статический HTML, 0 JS -->
<ReactButton />

<!-- С директивой — компонент становится интерактивным -->
<ReactButton client:load />

client:load — немедленная гидратация

Компонент гидратируется сразу после загрузки страницы. JS скачивается и выполняется с наивысшим приоритетом.

---
import NavMenu from '../components/NavMenu.jsx';
import CartIcon from '../components/CartIcon.jsx';
---

<NavMenu client:load />
<CartIcon client:load />

Используйте для: главного меню, форм входа, корзины, любых элементов, видимых сразу.

client:visible — гидратация при попадании в viewport

Компонент гидратируется, когда появляется в области просмотра. Использует IntersectionObserver под капотом. JS не загружается пока пользователь не доскроллит.

---
import CommentSection from '../components/CommentSection.jsx';
import NewsletterForm from '../components/NewsletterForm.jsx';
---

<article>
  <!-- ... статический контент ... -->
  <CommentSection client:visible />
  <NewsletterForm client:visible />
</article>

Используйте для: комментариев, форм подписки, виджетов ниже fold, карт.

client:idle — гидратация при простое браузера

Компонент гидратируется когда браузер завершил критические задачи и переходит в режим ожидания. Использует requestIdleCallback (или setTimeout как fallback).

---
import ChatWidget from '../components/ChatWidget.jsx';
import AnalyticsTracker from '../components/Analytics.jsx';
---

<ChatWidget client:idle />
<AnalyticsTracker client:idle />

Используйте для: чат-виджетов, push-уведомлений, некритической аналитики, рекомендаций.

client:only — только клиентский рендеринг

Компонент не рендерится на сервере. Hydration происходит полностью на клиенте. Требует явного указания фреймворка.

---
import MapView from '../components/MapView.jsx';
import ThreeDScene from '../components/ThreeDScene.jsx';
---

<!-- Компоненты, использующие browser-only API -->
<MapView client:only="react" />
<ThreeDScene client:only="react" />

Используйте для: Leaflet/Mapbox карт, Three.js сцен, компонентов с localStorage, canvas, WebGL.

client:media — гидратация по медиа-запросу

Компонент гидратируется только если CSS медиа-запрос совпадает с текущим viewport.

---
import MobileNav from '../components/MobileNav.jsx';
import DesktopSidebar from '../components/DesktopSidebar.jsx';
---

<MobileNav client:media="(max-width: 767px)" />
<DesktopSidebar client:media="(min-width: 1024px)" />

Используйте для: адаптивных меню, виджетов только для десктопа/мобайла.

Сравнение директив

Директива	Когда срабатывает	Влияние на LCP	Для чего
`client:load`	Сразу при загрузке	Высокое	Критический UI
`client:idle`	После загрузки страницы	Низкое	Некритический UI
`client:visible`	При прокрутке до элемента	Нулевое до scroll	Контент ниже fold
`client:only`	При загрузке (без SSR)	Среднее	Browser-only API
`client:media`	При совпадении медиа	Адаптивное	Responsive компоненты

Правильное использование

---
import Hero from '../components/Hero.jsx';
import Comments from '../components/Comments.jsx';
import Chat from '../components/Chat.jsx';
import Map from '../components/Map.jsx';
---

<!-- ✅ Критично — сразу -->
<Hero client:load />

<!-- ✅ Ниже fold — при прокрутке -->
<Comments client:visible />

<!-- ✅ Некритично — при простое -->
<Chat client:idle />

<!-- ✅ Только в браузере -->
<Map client:only="react" />