Next.js Starter

Production-ориентированный стартовый монорепозиторий на Next.js с общей библиотекой компонентов, типизированным API-клиентом, наблюдаемостью и browser-тестами.

Быстрый старт

Требования: Node.js 24 и поставляемая вместе с ним версия npm.

npm ci
test -e .env || cp .env.example .env
npx lefthook install
npm run dev

Откройте http://nextjs-starter.127.0.0.1.nip.io:3000. Имя разрешается через nip.io в 127.0.0.1, поэтому изменять системный hosts не нужно.

Команда не перезаписывает существующий .env. Приложение проверяет переменные окружения во время загрузки Next.js config. Если файл был создан раньше, сравните его с актуальным .env.example: новые обязательные переменные автоматически в него не попадут. Перед заменой локальных placeholder-значений прочитайте справочник переменных окружения.

Возможности

• Next.js 16 App Router, React 19, TypeScript 7 и Tailwind CSS 4.
• Включённые Cache Components; React Compiler работает только в production-сборках.
• npm workspaces для @repo/core и @repo/api.
• UI-примитивы в стиле Base UI/shadcn, безопасный HTML rendering и типизированная композиция TanStack Form в @repo/core.
• Исходный OpenAPI 3.2 contract, Redocly validation и сгенерированные Hey API TypeScript types, Next.js client, flat SDK, Zod schemas, TanStack Query options, Faker factories и cache tags. Facets экспортируются через @repo/api, /client, /query, /schemas, /mocks и /cache-tags.
• Server runtime mock mode на внутренних generated routes для работы без доступного backend; browser development пока ограничен BFF-prefix.
• Sentry, OpenTelemetry, Adze logging и Prometheus metrics.
• Vitest unit- и browser component projects, Playwright E2E и Storybook.
• Oxfmt, Oxlint, Knip, JSCPD, Lefthook и Commitizen.

Petstore contract в packages/api/openapi/ служит примером code generation. Он не добавляет Petstore backend или Next.js Route Handlers. Генератор закреплён на @hey-api/openapi-ts@0.99.0; его процесс использует изолированный TypeScript 6.0.3 compatibility alias, тогда как проверки приложения остаются на TypeScript 7. Pipeline и условие удаления этого shim описаны в руководстве по генерации API-клиента.

Формы

Переиспользуемые формы экспортируются из @repo/core/form через единую типизированную фабрику useAppForm. Она регистрирует поля text, textarea, number, date, phone, checkbox, switch, select, radio-group и slider вместе с SubmitButton.

Используйте нативный элемент <form> и передавайте его submit event экземпляру TanStack Form. Zod 4 schemas реализуют Standard Schema и могут передаваться напрямую, без resolver:

'use client'import{useAppForm}from'@repo/core/form'import{z}from'zod'constprojectSchema=z.object({name: z.string().min(3)})exportfunctionProjectForm(){constform=useAppForm({defaultValues: {name: ''},validators: {onChange: projectSchema},onSubmit: ({ value })=>{// Отправьте типизированное значение на границу приложения.},})return(<formonSubmit={(event)=>{event.preventDefault()voidform.handleSubmit()}}><form.AppFieldname="name">{(field)=><field.TextFieldlabel="Название проекта"/>}</form.AppField><form.AppForm><form.SubmitButton>Сохранить</form.SubmitButton></form.AppForm></form>)}

TanStack Form Devtools монтируются только в development и не попадают в production и test application paths. Поддерживаемые public subpaths и component workflow описаны в справочнике @repo/core.

Проверка

npm run verify:fast # форматирование, lint и TypeScript
npm run test# все Vitest projects
npm run test:e2e # Playwright E2E с development server
npm run verify # полный локальный набор проверок

Полная команда verify запускает verify:fast, Knip, JSCPD, все Vitest projects, а затем Playwright E2E. Lefthook форматирует staged files и использует verify:fast для pre-commit checks.

GitLab CI запускает verify:fast и Vitest на отдельных stages. Pipeline не выполняет standalone Playwright E2E и не создаёт готовую к deployment Next.js-сборку. .gitlab/deploy.yaml содержит только закомментированный template, поэтому pipeline не публикует release artifact и ничего не развёртывает. Будущий deploy job должен самостоятельно собрать или получить immutable bundle. Подробности находятся в правилах тестирования и руководстве по развёртыванию.

Служебные endpoints

• Health: /api/health
• Readiness: /api/ready
• Prometheus metrics: /api/metrics

Health и readiness сейчас всегда возвращают 200; readiness не проверяет upstream dependencies. Для локальной production-проверки выполните npm run build, затем npm run prod.

Документация

Начните с индекса документации. Основные документы:

• Архитектура
• Переменные окружения
• Генерация API-клиента
• BFF proxy
• Режим моков
• Кеширование и streaming
• Компоненты @repo/core
• Правила тестирования
• Конфигурация Oxlint
• Развёртывание