Гайд по работе со сборкой

Для начала работы у вас должент быть установлен Node.js 20

🚀 Структура проекта

Используется модульная архитектура

Нижележащий слой может испльзоваться только в слоях стоящих выше по иерархии

shared 🡒 ui 🡒 components 🡒 modules 🡒 pages

├── public/                 # статические файлы (иконки, картинки и тп.)
│   ├── icons/
│   ├── images/
│   ├── ...
│   └── favicon.ico
├── src/
│   ├── components/         # компоненты
│   │   ├── Modal/
│   │   └──  ...
│   ├── layouts/            # служебный слой для общих лэйаутов страниц
│   │   ├── Main/
│   │   ├── root/
│   │   ├── UI-kit/
│   │   └──  ...
│   ├── modules/            # модули ( могут иметь вложенные компоненты, своё состояние и изолированную логику )
│   │   ├── footer/
│   │   ├── header/
│   │   └── ...
│   ├── shared/             # общее ( переиспользуемые глобальные сущности не имеющие конкретной привязки )
│   │   ├── assets/
│   │   ├── const/
│   │   ├── scripts/
│   │   ├── settings/       # различные конфиги модалок, форм и т.д.
│   │   ├── helpers/
│   │   ├── styles/
│   │   └── types/
│   ├── ui/                 # элементы интерфейса ( базовые переиспользуемые ui компоненты )
│   │   ├── button/
│   │   └──  ...
│   └── pages/              # страницы ( лэйауты страниц )
│       ├── index.astro/
│       ├── sitemap.astro/
│       ├── ui-kit.astro/
│       └── ...
├── util/                   # утилиты ( автоматизация процессов, генерация компонентов, оптимизация картинок и тп. )
│   ├── component/
│   └── ...
├── package.json
└── ...

Все статические файлы, например svg или шрифты, могут лежать в папке public/. Оттуда все файлы автоматически попадают в билд.

🐱‍💻 Команды

Все команды запускаются из корня проекта:

Command	Action
npm install	Установить зависимости
npm run prepare	Инициализировать husky pre-commit
npm run dev	Запустить локальный дев сервер localhost:4321
npm run start	Запустить сервер c IP адресом localhost:IP
npm run build	Собрать билд для продакшна ./dist/
npm run preview	Посмотреть билд локально перед деплоем
npm run astro -- --help	Получить помощь в использовании Astro CLI
npm run lint	Запустить линтер с автоисправлениями
npm run gen:component	Утилита для создания шаблонного компонента
npm run images	Утилита для оптимизации изображений

🎴 Картинки

Есть два варианта для использования картинок:

1. Использовать компонент астро Picture. Он автоматически генерирует х1, х2, webp и avif. Автоматически подставляет ширину и высоту. Документация

Миксин генерирует все изображения из изначальной картинки (х1, х2, webp, avif) нужно только изначально прокинуть картинку х2

Используйте по согласованию с бэком или если бэка нет. Обязательно нужно указать ширину, чтобы правильно сгенерировались картинки х1.5

---
import { Picture } from "astro:assets";
import myImage from "@images/my-image.jpg";
---

<Picture
  src={myImage}
  alt="example image"
  quality={"high"}
  formats={["webp"]}
  width={image.width / 2}
  height={image.height / 2}
  densities={[2]}
/>

2. Использовать утилиту для оптимизации графики

npm run images

Исходники картинок для оптимизации хранятся в директории src/assets/images

Можно закидывать картинки в форматах jpg, jpeg, png. Желательно выгружать из макетов в хорошем качестве (2x, 3x)

Оптимизированные изображения сохраняются в папку public/images. Можно как очистить папку от ранее сгенерированных изображений, так и обновлять их свежими версиями (по умолчанию No)

В случае оптимизации ретинизированной графики (по умолчанию Yes), в название файла добавляется постфикс (@1x, @2x)

Генерация webp опциональна (по умолчанию Yes)

Можно использовать компонент ui/Picture/Picture.astro

---
import Picture from '@ui/Picture/Picture'
---

<Picture
  name="mountain"
  alt="Example image"
  format="jpg"
  width={1920}
  height={1280}
/>

Также добавлена возможность добавить адаптивное изображение для мобильной версии и задать брейкпоинт:

interface Props {
  ///
  mobileName?: string
  mobileBreakpoint?: number
  ///
}

♠️ Иконки

Все иконки должны быть в папке src/icons. Используйте компонент Icon, он вставляет svg инлайном на страницу. Спрайт собирается автоматически при множественном использовании одной иконки на конкретной странице.

---
import { Icon } from 'astro-icon/components'
---

<div class="icon">
  <Icon name="icon-close" />
</div>

Подробнее узнать можно тут.

Не используйте <img> для этого кейса, если нужно использовать svg в тэге <img>, добавляйте svg в папку public/.

📦 Слоты

Примеры использования можно посмотреть в доке, хотел лишь добавить что, если в вашем компоненте нужна проверка, принимает ли он слот или нет (например чтобы не генерировать лишнии пустые блоки которыми обернут слот) испрользуйте проверку 👇

<div class="card">
  ...
  {Astro.slots.has("buttons") && (
    <div class="card__buttons">
      <slot name="buttons">
      </slot>
    </div>
  )}
  ...
</div>

Слоты можно прокидывать через промежуточные компоненты: пример из доки

🧜 Полиморфные компоненты

В проекте есть полиморфные компоненты (Title, Button и т.д.) на основе пропса as="...", в который нужно передать желаемый html тэг. Это позволяет указать TS чтобы он подтянул нативные пропсы(аттрибуты) сам исходя из переданного тэга. Вы так же вы можете расширить TS-тип добавив нужные вам пропсы type Props<Tag extends HTMLTag> = Polymorphic<{as: Tag}> & { ..здесь ваши пропсы.. }.

📏 Адаптив и скейлинг

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

Брейкпоинты скейлинга задаются в константе SCALING_BREAKPOINTS (src/shared/const/_scaling.ts).

Каждый брейкпоинт в SCALING_BREAKPOINTS должен определять ширину экрана size, на которой будет произведён переход на него (с опциональным значением min для скейлинга вниз от брейкпоинта) и параметры fontSize для размера шрифта, устанавливаемого на тег html (обязательный базовый размер base и опциональные min и max для предотвращения чрезмерного уменьшения/увеличения размеров).

При задании размеров в стилях необходимо использовать функцию rem(), которая импортируется из 'styles/func':

@use '@styles/func';

.element {
  width: func.rem(100);
}

👀 Хотите узнать больше?

Посмотрите документацию Astro.

Используйте готовые компоненты из Лиги решений.

🐱‍🐉 Проблемы и предложения по сборке

Присылайте свои issues в gitHub репозиторий