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

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

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

Внутри проекта вы увидете следующие папки и файлы:

/
├── public/
│   ├── favicon.svg
│   ├── fonts/
│   └── svg/
├── src/
│   ├── components/
│   │   ├── Container/
│   │   │   ├── Container.astro
│   │   │   └── Container.scss
│   │   └── ...
│   ├── ui/
│   │   ├── Button/
│   │   │   ├── Button.astro
│   │   │   └── Button.scss
│   │   └── ...
│   ├── layouts/
│   │   ├── root/
│   │   │   └── root.astro
│   │   ├── Main/
│   │   │   └── Main.astro
│   │   └── ...
│   ├── pages/
│   │   ├── index.astro
│   │   ├── sitemap.astro
│   │   └── ui-kit.astro
│   ├── styles/
│   │   ├── components/
│   │   ├── global/
│   │   ├── vendors/
│   │   └── index.scss
│   ├── scripts/
│   │   ├── modules/
│   │   ├── utils/
│   │   └── index.js
│   └── images/
├── util/
└── package.json

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

🐱‍💻 Команды

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

🎴 Картинки

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

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

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

Используйте по согласованию с бэком или если бэка нет. Обязательно нужно указать ширину, чтобы правильно сгенерировались картинки х1.5 если не подходит, то используйте миксин из ui/Picture/Picture.astro генерация и оптимизация картинок через gulp webp, gulp optimize

---
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]}
/>

⚠️ Если вы используете исходные png картинки или преобразовываете через fallbackFormat="png" (а так же динамическое использование fallbackFormat=myImage.format) делайте в компоненте проверку как ниже т.к. squooshImageService который используется в оптимизации картинок, не умеет оптимизировать png.

---
import myImagePng from "@images/my-image-png.png";
---

<Picture
  ...
  quality={myImage.format === "png" ? null : "high"}
  ...
/>

Оптимизируйте png исходники вручную через tinypng.

♠️ Иконки

Все иконки должны быть в папке 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}> & { ..здесь ваши пропсы.. }.

⚙ Работа с экшенами

Для работы экшенов при создании репозитория нужно обязательно в разделе Actions => General выбрать чекбокс “Allow GitHub Actions to create and approve pull requests” (Скриншот).

Директория dist добавлена в файл gitigonre. Для создания папки dist на проекте настроены экшены. Для работы с ними на сайте гитхаба необходимо зайти во вкладку Actions и выполнить следующие действия:

1. Выбрать экшн, который нужно запустить. В сборке настроен экшен - Build, который собирает билд проекта в отдельную ветку build.
2. Нажать на кнопку Run workflow. В выпадающем списке убедиться, что экшн будет запущен из ветки master и нажать зеленую кнопку Run workflow.
3. После этого во вкладке Actions мы можем посмотреть на процесс выполнения нашего экшена. Когда экшн отработает корректно, напротив его названия появится зеленый значок, это означает что ошибок при его выполнении нет и он отработал корректно. После этого в списке веток репозитория должна появиться ветка build, в которой будет лежать наш собранный проект.

🤖 Автоматический деплой на хост gitHub

Нужно подключить gitHub pages в настройках репозитория: Settings => pages => Source => GitHub Pages.

Адрес хоста добавьте в информацию о репозитории (сверху справа на странице репозитория github). Хост будет автоматически обновляться после заливки в мастер.

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

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

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

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

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