Серверные островки

Серверные островки позволяют рендерить динамические или персонализированные части страницы («островки») по запросу, не снижая общую скорость загрузки.

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

Компоненты серверных островков

Серверный островок — это обычный компонент Astro, рендеринг которого намеренно отложен до момента готовности данных.

Страница отображается сразу с резервным контентом. Затем содержимое островка запрашивается с сервера и отображается по мере готовности.

Чтобы включить эту функцию, добавьте директиву server:defer к любому компоненту:

src/pages/index.astro

---
import Avatar from '../components/Avatar.astro';
---
<Avatar server:defer />

Внутри такого компонента можно выполнять любые действия, доступные при рендеринге по запросу (SSR): получать данные из БД, работать с куками и т. д.

src/components/Avatar.astro

---
const userSession = Astro.cookies.get('session');
const avatarURL = await getUserAvatar(userSession);
---
<img alt="Аватар пользователя" src={avatarURL} />

Передача пропсов

Пропсы для серверных островков должны быть сериализуемыми (строки, числа, объекты, массивы и т.д.). Передавать функции в компоненты с server:defer нельзя.

Резервный контент серверных островков

Вы можете указать, что показывать пользователю, пока островок загружается, используя именованный слот fallback:

---
import Avatar from '../components/Avatar.astro';
import GenericAvatar from '../components/GenericAvatar.astro';
---
<Avatar server:defer>
  <GenericAvatar slot="fallback" />
</Avatar>

Это может быть:

• Универсальный аватар вместо личного.
• Заглушки с текстом (Skeleton UI).
• Индикаторы загрузки (спиннеры).

Как это работает

Реализация серверных островков происходит в основном во время сборки:

1. Каждому острову с server:defer выделяется скрытый маршрут.
2. Вместо компонента в HTML вставляется небольшой скрипт и резервный контент.
3. При загрузке страницы браузер запрашивает содержимое острова через специальный эндпойнт.
4. Острова загружаются независимо друг от друга, поэтому медленный блок не затормозит всю страницу.

Кеширование

Данные для островов передаются через зашифрованную строку в URL. Это позволяет кешировать результаты запросов с помощью стандартных HTTP-заголовков Cache-Control.

Если параметров слишком много и URL превышает 2048 байт, Astro переключится на POST-запросы, которые не кешируются браузерами. Рекомендуется передавать в острова только минимально необходимые данные.

URL страницы в серверном островке

Серверные острова работают в изолированном контексте. Значения Astro.url внутри острова будут указывать на технический эндпойнт (например, /_server-islands/Avatar).

Чтобы получить URL исходной страницы, используйте заголовок Referer:

---
const referer = Astro.request.headers.get('Referer');
const url = new URL(referer);
const productId = url.searchParams.get('product');
---