Учебное руководство
Небольшой проект с настоящим сайтом на Next.js, типизированным API, CMS и фоновыми задачами в контейнерах на одном VPS. Публичное оформление использует название и материалы «Атмановских кулачек».
Руководство описывает код на 2026-10-05. Команды выполняются из корня репозитория, если не указан другой каталог. Изменения SSG/ISR и 404 пока находятся в рабочей версии: локальная проверка не означает, что они уже выложены на стенд. Будущие возможности помечены как упражнения или ограничения.
Порядок чтения
Онлайн-версия: учебное руководство. Устройство публикации описано в отдельной главе.
| Глава | Что узнаете |
|---|---|
| Быстрый старт | Требования, первый запуск, три режима разработки, первая проверка |
| Архитектура | Роли приложений, монорепозиторий, зависимости, путь данных |
| Сайт и Mantine | App Router, серверные и клиентские компоненты, статическая сборка, тема |
| SSG, ISR и 404 | Генерация HTML, кеш, webhook, новые адреса и проверка обновления |
| Вход и панели | Сессии, русский язык, оформление и сборка панелей |
| API и контракты | tRPC, Zod, входные данные, HTTP-коды, границы доверия |
| Фоновые задачи | Hatchet, события, воркер, повторы, параллельность, доставка |
| CMS и контент | Strapi, повторяемый импорт, Blocks, публикация и фотографии в Garage |
| Docker и сеть | Образы, Compose, порты, базы, тома, readiness |
| Настройки и секреты | Все переменные, локальная и production-конфигурации, ротация |
| GitHub Actions и VPS | Подготовка хоста, pipeline, release, digest, откат |
| Эксплуатация | Диагностика, резервные копии, восстановление, обновления |
| Проверки | TypeScript, Oxlint, Oxfmt, Jest, что именно покрыто |
| Разбор проблем | Симптом → проверка → причина → действие |
| Ограничения и безопасность | Что нельзя считать реализованным или гарантированным |
| Практикум | Упражнения с критериями результата, от первого изменения до CMS |
| Словарь и источники | Термины, карта команд и официальные документы |
Маршруты обучения
- Первое знакомство: быстрый старт → архитектура → сайт → практикум, задания 1–3.
- Backend: API → воркеры → CMS → проверки → практикум, задания 4–7.
- Развёртывание: инфраструктура → настройки → деплой → эксплуатация → ограничения.
Во время чтения держите открытым исходный файл из раздела «Где смотреть код». Попробуйте сначала предсказать результат команды, затем сравнить его с фактическим. Так проще отличить TypeScript от runtime-валидации, сборку от запуска и доставку события от выполнения задачи.
Главная особенность проекта
Публикация Strapi меняет сайт без пересборки. Страницы генерируются статически; webhook напрямую инвалидирует кеш Next.js, а ISR обновляет HTML.
Для каждого изменения используйте цикл: небольшое изменение → подходящая проверка → отдельный коммит. Не проверяйте сбои и восстановление на публичном VPS, если то же упражнение можно выполнить локально.
S3-хранилище
По запросу пользователя добавлен отдельный Garage-контейнер. Настройка, совместимость provider и резервные копии. План переноса контента учитывает S3, новый слой компонентов и сохранность редакторских правок.
Фактические результаты переноса: отчёт о миграции.
Переиспользуемый UI
UIKit на Mantine и Storybook: базовые компоненты, составные блоки, независимое подключение, CSS-каскад и CMS-адаптеры.
Повторное визуальное сравнение после UIKit: снимки production, проверки и оставшиеся отличия.
Учебный раздел Storybook содержит шесть глав: введение, подключение, тему и стили,
композицию, создание stories/docs и практикум. Исходники —
packages/ui/src/docs; после pnpm --filter @gheilt/ui storybook
главы находятся в разделе «Обучение».