Astro.js

# Правила архитектуры Astro v6 (строгий режим)

## 1. Основная философия

- Следуй принципу Astro «HTML прежде всего / никакого JavaScript по умолчанию»:
  - Всё является статическим HTML, если интерактивность явно не требуется.
  - JavaScript — это затраты → добавляй его только тогда, когда он создаёт реальную ценность для пользователя.

- Всегда мысли в рамках «островной архитектуры»:
  - Страница — это статический HTML
  - Интерактивные части — изолированные острова
  - Никогда не рассматривай всю страницу как приложение

- Прежде чем писать любой JavaScript, всегда спрашивай:
  «Можно ли решить это с помощью HTML + CSS или серверной логики?»

---

## 2. Модель компонентов

- Используй компоненты `.astro` для:
  - Макета
  - Композиции
  - Статического интерфейса
  - Получения данных
  - Серверной логики (frontmatter)

- Компоненты `.astro`:
  - Выполняются во время сборки или на сервере
  - По умолчанию НЕ отправляют JavaScript
  - Должны оставаться независимыми от фреймворка

- НИКОГДА не используй хуки React/Vue/Svelte внутри `.astro`

---

## 3. Острова (интерактивные компоненты)

- Используй компоненты фреймворков (React, Vue, Svelte и т. д.) только для интерактивности.

- Рассматривай каждый интерактивный компонент как изолированный остров:
  - Независимый
  - Самодостаточный
  - С минимальной областью ответственности

- НИКОГДА:
  - Не гидратируй целые страницы или макеты
  - Не оборачивай большие деревья в один остров
  - Не создавай без необходимости множество маленьких островов в циклах

- Предпочитай:
  - Статический рендеринг списков
  - Гидратацию только минимальной интерактивной единицы

---

## 4. Стратегия гидратации (критически важно)

- Всегда явно определяй гидратацию с помощью директив `client:*`.

- Выбирай САМЫЙ НИЗКИЙ возможный приоритет:

  - `client:load`
    → Только для критически важной интерактивности на первом экране

  - `client:idle`
    → Для второстепенного интерфейса после загрузки страницы

  - `client:visible`
    → Для компонентов ниже первого экрана или тяжёлых компонентов

  - `client:media`
    → Для адаптивного / условного интерфейса

  - `client:only`
    → ТОЛЬКО когда SSR ломается (window, localStorage и т. д.)

- Правило по умолчанию:
  ❌ Никогда не выбирай `client:load` по умолчанию
  ✅ Предпочитай `client:visible` или `client:idle`

- Гидратация — это бюджет производительности:
  - Каждый остров добавляет JS
  - Сохраняй общий объём JS минимальным

📌 Astro НЕ гидратирует компоненты, если это явно не указано через `client:*` :contentReference[oaicite:0]{index=0}  

---

## 5. Серверная и клиентская логика

- Предпочитай серверную логику (внутри frontmatter `.astro`) для:
  - Получения данных
  - Преобразований
  - Фильтрации / сортировки
  - Производных значений

- Используй клиентское состояние только когда:
  - Этого требует взаимодействие пользователя
  - Нужны обновления в реальном времени

- Избегай:
  - Дублирования логики на клиенте
  - Переноса серверной логики в острова

---

## 6. Управление состоянием

- Избегай клиентского состояния, если оно не является строго необходимым.

- Если оно нужно:
  - Ограничивай состояние только пределами острова
  - НЕ создавай глобальное состояние приложения без необходимости

- Для состояния между островами:
  - Используй легковесные общие хранилища (например, nano stores)
  - По умолчанию избегай тяжёлых систем глобального состояния

---

## 7. Ограничения производительности (жёсткие правила)

- Минимизируй JavaScript, отправляемый клиенту:
  - Astro загружает JS только для гидратированных компонентов :contentReference[oaicite:1]{index=1}  

- Предпочитай:
  - Статический рендеринг
  - Частичную гидратацию
  - Отложенную гидратацию

- Избегай:
  - Гидратации больших списков
  - Повторяющихся островов в циклах
  - Чрезмерного использования `client:load`

- Каждый остров:
  - Имеет собственный бандл
  - Загружается независимо
  - Должен оставаться небольшим и узконаправленным :contentReference[oaicite:2]{index=2}  

---

## 8. Структура файлов и проекта

- `/pages`
  - Точки входа (SSG/SSR)
  - Никакой клиентской логики

- `/components`
  - Общий интерфейс
  - Здесь находятся острова

- `/layouts`
  - Только статические обёртки

- `/content`
  - Markdown / данные CMS

- Сосредоточь файлы `.astro` на композиции, а не на поведении

---

## 9. Антипаттерны (строго запрещены)

- ❌ Использование хуков в `.astro`
- ❌ Превращение Astro в SPA-архитектуру
- ❌ Гидратация всего макета/страницы
- ❌ Использование `client:load` повсюду
- ❌ Преобразование списков в гидратированные компоненты
- ❌ Использование клиентского JS для статических задач
- ❌ Замена серверной логики клиентской

---

## 10. Предпочтительные паттерны

- ✅ Рендеринг с приоритетом статики
- ✅ Минимальные, изолированные острова
- ✅ Отложенная гидратация (`visible`, `idle`)
- ✅ Серверные вычисления
- ✅ HTML + CSS прежде JS
- ✅ Прогрессивное улучшение

---

## 11. Система принятия решений (ОЧЕНЬ ВАЖНО)

Для каждой функции:

1. Может ли это быть статическим HTML?
   → ДА → Используй `.astro`

2. Требуется ли взаимодействие?
   → НЕТ → Оставайся в статике

3. Требуется ли JS?
   → ДА → Создай остров

4. Когда это должно загружаться?
   → Выбери САМЫЙ НИЗКИЙ приоритет `client:*`

---

## 12. Ментальная модель (не обсуждается)

- Astro — это НЕ:
  - Next.js
  - SPA-фреймворк
  - Система с приоритетом React

- Astro — это:
  - Рендерер с приоритетом статики
  - Система частичной гидратации
  - Архитектура с приоритетом производительности

- Мысли так:
  ❌ «Построить приложение»
  ✅ «Отправить HTML + добавить немного JS»