Платформа для маркетингового сайта и документации

Описание

Проект представляет собой многоязычную (en/ru) платформу на базе Next.js 14 для публичного лендинга и раздела документации. Интерфейс собран из библиотек shadcn/ui и Tailwind CSS, а контент генерируется из DSL-спецификаций, обеспечивая повторное использование блоков и единый источник данных для команд разработки и контента.

Основные возможности

• Маркетинговая страница с героем, списком преимуществ, таблицей данных и группой CTA-кнопок. В Hero-блоке поддерживается fallback-лоадер для имитации загрузки данных.
• Раздел документации с отдельным layout и набором блоков, повторно использующих UI-компоненты проекта.
• Универсальные UI-компоненты: герой, список фич, таблица данных, кнопки и спиннер реализованы как независимые модули с поддержкой вариантов отображения.
• Локализация через next-intl и middleware с автоматическим выбором языка и подстановкой переводов в шаблоны страниц.
• Генерация страниц из DSL: YAML-спецификации описывают структуру страниц, а скрипты автоматически подтягивают компоненты и собирают React-код.
• API-блоки и Supabase-типы: DSL поддерживает серверные блоки (api) с типобезопасными вызовами (например, @api/supabase-query) и позволяет подключать сгенерированные Supabase-типы через секцию imports.
• Автоматическое управление переводами: скрипт извлекает ключи i18n и синхронизирует файлы локалей.

Технологический стек

• Next.js 14 с включённым reactStrictMode и статической генерацией по умолчанию.
• React 18 и серверные компоненты, совместимые с клиентскими блоками через "use client" в сгенерированных файлах.
• Tailwind CSS для стилизации UI, сканирующий каталоги app, components и lib.
• next-intl и JSON-файлы в locales/ для управления переводами.

Структура каталогов

• app/ — маршруты Next.js, сгруппированные по локали и layout-группам.
• components/ui/ — переиспользуемые визуальные блоки интерфейса.
• dsl-pages/ — DSL-описания страниц для автогенерации.
• locales/ — JSON-файлы переводов, поддерживающие ключи, используемые в DSL.
• schemas/ — описания схем DSL на базе Zod для валидации во время генерации.
• scripts/ — служебные утилиты для генерации страниц, загрузки компонентов и синхронизации переводов.

Скрипты package.json

• pnpm dev — запуск локального дев-сервера Next.js.
• pnpm build / pnpm start — продакшен-сборка и запуск.
• pnpm lint — запуск ESLint для проверки качества кода.
• pnpm typecheck — проверка TypeScript без генерации артефактов.
• pnpm apg:generate — генерация страниц на основе DSL и автоподключение недостающих компонентов.
• pnpm apg:extract — синхронизация переводов с DSL и внешними сервисами.

Начало работы

1. Установите зависимости: pnpm install.
2. Для автоматического флоу опишите страницу простыми словами и выполните pnpm apg:agent. Скрипт обратится к AI-агенту, сгенерирует YAML, покажет его для подтверждения и только после вашего согласия создаст файл в dsl-pages/ и итоговую страницу в app/.
3. Если DSL уже подготовлены вручную, выполните генерацию напрямую: pnpm apg:generate.
4. Запустите локальный сервер: pnpm dev и откройте http://localhost:3000.
5. Для поддержки новых ключей i18n выполните pnpm apg:extract после обновления DSL-спецификаций.

Процесс разработки

• Новые страницы обычно появляются через pnpm apg:agent: вы описываете задачу человеческим языком, агент предлагает YAML, просит подтверждение и только затем сохраняет файл и запускает генерацию React-страницы.
• При необходимости можно продолжать работать вручную — добавьте YAML/JSON-файл в dsl-pages/ и выполните pnpm apg:generate.
• Если страница использует компоненты из внешних реестров shadcn/ui, скрипт автоматически подтянет их или запросит генерацию через Vercel v0 при наличии API-ключа.
• Переводы для ключей @i18n.* автоматически добавляются в локали, что упрощает ведение многоязычного контента.

Дополнительные материалы

• Lighthouse CI конфигурация хранится в lighthouserc.json для оценки перформанса и доступности.
• Шаблоны hygen для массовой генерации страниц доступны в _templates/ и скрипте scripts/generate-dsl.sh (массовое создание заготовок + генерация DSL).