Словарь, команды, версии и первоисточники
Версии, закреплённые в репозитории
Это снимок manifests/Compose на 2026-10-02, а не рекомендация автоматически обновиться на «последнюю» версию.
| Инструмент | Версия/ветка | Где закреплён |
|---|---|---|
| Node.js | 24.x | engines, Dockerfile и Actions |
| pnpm | 12.8.1 | root packageManager |
| TypeScript workspace | 7.0.2 | package manifests |
| Next.js | 16.3.8 | web/package.json |
| React web | 19.2.8 | web/package.json |
| Mantine core/hooks | 9.6.3 | web/package.json |
| tRPC client/server | 11.19.0 | web/package.json |
| Blocks renderer | 1.0.2 | web/package.json |
| parse5 | 8.0.1 | infra/strapi/package.json |
| Zod | 4.6.5 | contracts/package.json |
| Hatchet SDK | 1.33.2 | web и functions manifests |
| Garage S3 | 2.3.0 | compose.yaml |
| Hatchet Lite | v0.107.0 | compose.yaml |
| Strapi | 5.56.0 | infra/strapi/package.json |
| React / TypeScript CMS | 18.x / 5.x | Собственный npm lockfile CMS |
| PostgreSQL | 17-alpine | compose.yaml |
| Caddy | 2-alpine | compose.yaml |
| Jest | 30.5.2 | web/package.json |
| Oxlint / Oxfmt | 1.86.0 / 0.71.0 | root devDependencies |
Версии SDK и Hatchet server не обязаны совпадать номером. Обновляйте их с проверкой
совместимости API и настоящего выполнения задачи. Strapi имеет отдельный lockfile;
root pnpm install его не переписывает.
Все корневые команды
| Команда | Реальное действие |
|---|---|
pnpm dev | contracts build → Next dev |
pnpm dev:functions | contracts build → Node watch worker |
pnpm setup | Создать локальный .env один раз |
pnpm infra:s3 | Garage health → включить website bucket media |
pnpm infra:up | PostgreSQL + Hatchet + Garage, wait |
pnpm infra:token | Получить token Hatchet в .env |
pnpm infra:token --rotate | Получить новый token, даже если строка уже есть |
pnpm stack:up | Profile app, build и wait всех контейнеров |
pnpm stack:down | Остановить и удалить контейнеры/сеть, сохранить volumes |
pnpm build | Рекурсивная сборка workspace |
pnpm start | Next start; для standalone смотрите troubleshooting |
pnpm typecheck | Workspace typecheck, включая Next typegen |
pnpm lint | Oxlint, warnings считаются ошибками |
pnpm format | Oxfmt, изменяет файлы |
pnpm format:check | Oxfmt readonly-проверка |
pnpm test | Серверные тесты web |
node scripts/check-static-site.mjs | Изолированная CMS, полный check и production ISR smoke |
pnpm check | build → typecheck → lint → format check → test |
pnpm --filter <package> <script> выбирает пакет. Команды root и package с
одинаковым названием могут иметь разный охват. Например, root build собирает
workspace, а web build — только Next. Scripts infra:* и setup существуют только
в корне, поэтому инструкции этого руководства используют корень по умолчанию.
allowBuilds в workspace фиксирует запрещённые install scripts отдельных
зависимостей. Это осознанная install policy, а не гарантия, что любая будущая версия
зависимости заработает без её lifecycle script. Не разрешайте все scripts автоматически
при первой ошибке установки. Lockfile и policy рассматривайте вместе.
Карта важных файлов
| Файл/группа | Что искать |
|---|---|
| package.json | Команды, engines, версии tooling |
| pnpm-workspace.yaml | Пакеты, install policy |
| tsconfig.base.json | Базовый Node ESM TypeScript |
| web layout | Общая оболочка, metadata, noindex |
| web next config | Standalone, trace root, HTTP headers |
| repository | CMS validation, published reading, media normalization |
| router | Read-only процедуры |
| contracts | Runtime input и типы |
| worker | Task definition и registration |
| Compose | Сервисы, зависимости, volumes, local defaults |
| production override | Образы, домены и административный доступ |
| workflow | CI и release pipeline |
| release.sh | Применение и best-effort rollback |
Schemas, controllers, routes и services CMS находятся в infra/strapi/src/api.
Конфиги в infra/strapi/config описывают HTTP, БД, admin secrets, plugins и middleware.
Upload plugin ограничивает типы файлов, в частности запрещает SVG для CMS upload;
исходный SVG конвертируется в PNG импортёром; frontend получает CMS media.
Словарь
| Термин | Значение в этом проекте |
|---|---|
| Монорепозиторий | Один Git-репозиторий с несколькими приложениями/пакетами |
| Workspace | Набор пакетов, которые pnpm устанавливает и связывает вместе |
| Lockfile | Конкретные версии и дерево установленных зависимостей |
| ESM | Модули JavaScript с import/export |
| Type checking | Проверка программы до выполнения |
| Type stripping | Удаление TS-аннотаций Node без проверки типов |
| Runtime validation | Проверка настоящего значения во время выполнения |
| Zod schema | Исполняемое определение требований к данным |
| Contract | Общая договорённость producer/consumer о форме сообщения |
| App Router | Файловая модель страниц/HTTP handlers Next.js |
| Server Component | Компонент, работающий на серверной стороне дерева React |
| Client Component | Компонент внутри границы use client, с браузерной логикой |
| Hydration | Подключение интерактивной React-логики к первоначальному HTML |
| SSR | Подготовка HTML сервером |
| Prerender/SSG | Подготовка страницы заранее, в том числе при сборке |
| Revalidation | Обновление ранее подготовленного/кэшированного представления |
| Slug | Человекочитаемый идентификатор в URL |
| Metadata | Заголовок, описание и инструкции robots страницы |
| Caller | Вызов tRPC router внутри сервера без HTTP |
| Procedure | Отдельная типизированная операция tRPC |
| Query / mutation | Чтение / изменение; текущий router содержит queries |
| Webhook | HTTP-сообщение об изменении от CMS к нашему web |
| Producer | Тот, кто отправляет событие; route handler |
| Consumer | Тот, кто получает и обрабатывает сообщение |
| Event | Факт/сообщение, которое может инициировать task |
| Task | Определение фонового обработчика |
| Run | Конкретное выполнение определения |
| Worker | Долгоживущий процесс-исполнитель |
| Tenant | Отдельная область данных/работ Hatchet |
| gRPC | Протокол соединения SDK/worker с Hatchet |
| Retry | Новая попытка после ошибки |
| Idempotency | Повтор операции не создаёт лишний бизнес-эффект |
| Outbox | Запись предназначенного к отправке сообщения в одной транзакции с данными |
| Image | Собранная файловая система и metadata приложения Docker |
| Container | Запущенный экземпляр image |
| Volume | Хранилище, переживающее пересоздание контейнера |
| Bind mount | Монтирование конкретного пути хоста в контейнер |
| Profile | Условная группа запуска сервисов Compose |
| Healthcheck | Периодическая проверка контейнера |
| Readiness | Готовность выполнить ожидаемую операцию |
| Reverse proxy | Принимает внешний запрос и пересылает нужному сервису |
| TLS | Защита сетевого соединения HTTPS |
| Basic Auth | Дополнительная HTTP-аутентификация Caddy перед панелями |
| JWT | Подписанный token; наличие текста не означает действительность |
| Digest | Идентификатор конкретного содержимого image |
| GHCR | GitHub Container Registry |
| Release | Набор Compose/config/image references конкретного commit |
| Rollback | Возврат версии приложения; здесь не откат данных |
| Backup | Сохранённая копия данных и ключей |
| Restore drill | Проверенное восстановление в отдельном окружении |
Официальные источники
Ссылки дополняют чтение нашего кода; latest-документация может описывать отличия от закреплённых версий. Начинайте с версии manifest, не копируйте пример из другого major.
- pnpm workspace.
- pnpm deploy.
- Node 24: TypeScript runtime.
- Next.js Server/Client Components.
- Next.js output/standalone.
- Mantine с Next.js.
- tRPC server-side calls.
- Zod.
- Hatchet.
- Исходники закреплённого Hatchet.
- Strapi models.
- Compose startup order.
- Caddy reverse_proxy.
- PostgreSQL 17 pg_dump.
- GitHub Actions: публикация Docker images.
Изучайте инструмент на конкретной операции: найдите определение в коде, воспроизведите в локальной среде, объясните результат и только затем расширяйте функциональность.