Статическая библиотека на Astro

Соберём библиотеку «Полка», где содержание хранится в Markdown, а общий интерфейс задаётся компонентами Astro. Первая задача — подготовить маленький статический проект с закреплённой зависимостью и одной страницей. Это самостоятельный учебный пример на основе опыта ProfessorWeb; он не заменяет существующую сборку сайта и не переносит её опубликованные адреса автоматически.

В примерах закреплён Astro 7.3.8. Версия подтверждена метаданными официального npm-реестра на 11 октября 2026 года. Для неё требуется Node.js не ниже 22.12.0. Мы не пишем latest в зависимости: новая версия пакета не должна незаметно менять поведение всех этапов серии. При самостоятельной установке возникнет lockfile, который нужно сохранить вместе с проектом. Установка при подготовке этих материалов не выполнялась.

Что находится в исходниках и что получает посетитель

package.json разделяет три действия. dev предназначен для разработки, build создаёт статический выпуск, preview позволяет рассмотреть результат сборки локально. Ни одна из команд сама по себе не загружает файлы на ProfessorWeb. Запуск разработки и передача готового выпуска имеют разные договоры, особенно когда позднее появятся старые адреса с расширением PHP.

Конфигурация задаёт output: 'static'. В этом режиме маршруты заранее превращаются в HTML, а хостинг выдаёт полученные файлы. Мы не подключаем адаптер сервера и не рассчитываем на базу данных во время запроса. Статья меняется после изменения исходника и новой сборки. Для оперативного редактирования персональных данных такой режим имел бы другие ограничения, но учебная библиотека подходит для него.

Поле site содержит учебный домен https://polka.example. Он нужен при построении абсолютных адресов, но не является существующим сайтом серии. Перед настоящим выпуском его потребуется заменить. Не переносите в canonical localhost только потому, что разработка ведётся локально: производственный адрес является отдельной настройкой, а не случайным свойством текущего окна.

Первая страница находится в src/pages/index.astro. Код между разделителями в верхней части выполняется при подготовке страницы. Он не становится автоматически браузерным JavaScript. Значение title подставляется в документ, а посетитель получает обычную разметку. Это различие объясняет, почему для статической библиотеки не нужно доставлять в браузер все зависимости, использованные при сборке.

tsconfig.json наследует строгий профиль Astro. Это не означает, что компилятор уже запущен и подтвердил отсутствие ошибок. Профиль задаёт будущую среду типизации для схемы и компонентов. В архиве нет node_modules, .astro и готового dist: это производные данные конкретной установки. Каждый этап содержит исходники, которые следует рассматривать как отдельное состояние.

Ожидаемый результат после разрешённого запуска — одна страница с названием «Полка» и описанием библиотеки. Сейчас команды приведены как инструкция читателю и не выполняются. Следующий этап добавит пять материалов и общий контракт метаданных. Пока важно различать содержимое проекта, действия сборщика и файлы, которые в итоге получит посетитель.

Полный файл package.json текущего этапа:

{
  "name": "polka-content-lab",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=22.12.0"
  },
  "scripts": {
    "dev": "astro dev --host 127.0.0.1",
    "build": "astro build",
    "preview": "astro preview --host 127.0.0.1"
  },
  "dependencies": {
    "astro": "7.3.8"
  }
}

Полный файл astro.config.mjs текущего этапа:

import { defineConfig } from 'astro/config';
export default defineConfig({ output: 'static', site: 'https://polka.example', build: { format: 'preserve' } });

Полный файл src/pages/index.astro текущего этапа:

---
const title = "Полка";
---
<!doctype html><html lang="ru"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>{title}</title></head><body><main><h1>{title}</h1><p>Статическая библиотека учебных материалов.</p></main></body></html>

Разбор состояния библиотеки

Рассмотрим границу между компонентом и конечным файлом. index.astro может импортировать другие компоненты, выполнять подготовку данных и использовать типы. После сборки посетитель не получает весь этот процесс как исполняемую программу. Он получает результат, например HTML, CSS и только явно подключённые сценарии. Поэтому большой граф зависимостей редакционной среды и расходы первой страницы не являются одним числом.

Отдельное значение имеет папка public. Ресурс из неё передаётся с известным именем без превращения в страницу-компонент. Но это не место для всех исходников проекта. Если случайно положить редакционные заметки и секретные настройки в public, статический выпуск может их раскрыть. Схема каталогов помогает понимать намерение, однако реальная приватность требует не включать такие данные в передаваемый набор.

Запуск команд должен происходить из выбранной папки одного этапа. Если взять package.json первого урока и компоненты двенадцатого, появятся зависимости и настройки, которых в раннем состоянии ещё нет. Архив хранит полные снимки именно для уменьшения такой путаницы. Он не предлагает применять все папки как последовательные патчи к одному произвольному каталогу. Для изучения изменений сравнивайте соседние состояния, затем выбирайте одно целиком.

Необходимая версия Node относится к среде подготовки. Даже если на хостинге стоит другой runtime, это не обязательно мешает статической выдаче уже готового HTML. Но среда сборки должна удовлетворять требованиям пакета. Противоположная ошибка — считать, что установленный на сервере современный Node автоматически обеспечивает правильные canonical и старые URL. Runtime не решает адресную политику проекта.

Для самостоятельного изменения замените название и первый абзац главной страницы, сохранив выбранную конфигурацию. После будущей сборки сравните исходник и полученный документ. Найдите в HTML фактическое значение title, а затем убедитесь, что переменная из frontmatter не превращена в обязательный браузерный обработчик. Такой разбор показывает направление преобразования без подключения отдельного UI-фреймворка.

Если проект позже потребует личный кабинет, статическая модель не запрещает добавить внешний API или отдельный сервер. Однако это будет новый договор безопасности, данных и ошибок. Не обещайте закрытые личные сведения в заранее созданных публичных файлах. Серия начинается с общей библиотеки, поэтому ограничение static здесь соответствует содержанию и остаётся честным основанием архитектуры.

В исходниках нет готового package-lock, поэтому команды npm ci пока не предлагаются как немедленно выполнимые. Сначала потребуется разрешённая установка и сохранение полученного lockfile, затем можно выбрать воспроизводимую установку для следующей среды. Не создавайте искусственный файл со случайными integrity-значениями. Он должен описывать реальный разрешённый граф пакетов. Для чтения серии достаточно изучить package.json и полный снимок этапа без такого исполнения.

Условия для самостоятельного наблюдения

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

Условие	Ожидаемое состояние и его граница
Исходник страницы	Файл .astro участвует в подготовке HTML, его frontmatter не доставляется как браузерный сценарий.
Статический режим	Выдача уже готовой страницы не требует выполнения Node на каждом запросе.
Учебный домен	polka.example является настройкой примера, а не подтверждением существующей публикации.
Зависимости не установлены	Архив не содержит lockfile и node_modules, будущая среда должна закрепить результат установки.
Команда разработки	Dev предназначен для локального изменения проекта и не равен производственному выпуску.
Старые PHP адреса	Их совместимость ещё не реализована, отдельный этап объяснит границу генератора и хостинга.

Оглавление серии, курсы ProfessorWeb и полный архив исходников. Для этого урока выберите lesson-01.

Первичные источники: Astro installation, Astro 7 upgrade, Astro npm metadata.

Редакционный статус: локальный черновик. Установка, учебные программы, браузерные сценарии, тесты и публикация не выполнялись. Описанные эффекты ожидаемые.