Next.js Super Boilerplate v0.2: security layer, account management и AI-ready из коробки

Версия: 0.2.0 · Июнь 2026
Репозиторий: github.com/Fedorrychkov/nextjs-super-boilerplate
Демо: nextjs-super-boilerplate.visn-ai.io

Когда запускаешь продукт на Next.js в одиночку или небольшой командой, первые недели обычно уходят не на продукт. Они уходят на auth, на сброс пароля, на «как сделать так, чтобы отзыв сессии работал немедленно, а не через час пока не протухнет access token», на настройку SEO, Docker, CI — и так по кругу.

Next.js Super Boilerplate (NSB) — это попытка один раз решить эти задачи правильно и дать разработчику (и вайбкодеру с ИИ-ассистентом) точку старта, которая уже готова к production.

v0.2 — это не косметика. Это полноценный security & account layer поверх уже рабочей базы v0.1.

Содержание

• Для кого

• Стек и принципы

• Что нового в v0.2

• Auth: почему здесь всё по-другому

• Пароли, восстановление, MFA

• Сессии и устройства

• Онбординг

• Контент-платформа

• SEO и AI-агенты

• Push-уведомления

• LLM в редакторе

• Наблюдаемость и админка

• Новый интерфейс: лендинг и статьи

• Конфигурация и DX

• Деплой

• Чего здесь нет

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

Для кого

NSB — self-hosted стартер. Вы поднимаете свой MongoDB, свой сервер, свой домен. Никакого vendor lock-in, никаких скрытых платежей за инфраструктуру.

Хорошо подходит, если нужно:

• запустить продукт с личным кабинетом, ролями и контентом — быстро, без изобретения велосипедов;

• вести публичный блог или базу знаний с нормальным SEO;

• иметь CI/CD, Docker и мониторинг из коробки;

• работать с ИИ-ассистентом (Claude, Cursor) — кодовая база следует предсказуемым паттернам, которые LLM хорошо читают.

Менее подходит: Stripe, multi-tenant SaaS, hosted deploy без собственного сервера — это придётся достраивать.

Стек и принципы

Четыре архитектурных принципа:

1. **Feature flags в `config/env.ts`** — включаете только то, что нужно; всё опциональное отключено по умолчанию.

2. **Один файл брендинга `config/product.ts`** — название, автор, ссылки, PWA, JSON-LD.

3. **Тонкие роуты** — бизнес-логика в сервисах и server actions, не в route handlers.

4. **Серверные секреты не утекают** — JWT, LLM API key, email — только на сервере.

Что нового в v0.2

Версия 0.1 дала базу: auth, CMS, SEO, деплой, LLM-редактор. Версия 0.2 закрыла то, что нужно любому продакшен-продукту, но редко бывает в стартерах.

Auth: почему здесь всё по-другому

Большинство JWT-бойлерплейтов имеют фундаментальную дыру: вы отзываете refresh token, но access token живёт ещё час. Пользователь технически «разлогинен», а API всё ещё отвечает 200.

В NSB это решено правильно. В access JWT есть поле sid — идентификатор документа RefreshToken в БД. На каждом authenticated запросе middleware проверяет, что сессия с этим sid ещё существует и не отозвана.

Revoke сессии = немедленный 401. Без ожидания, без гонок, без «ну оно само протухнет».

Это не rocket science, но это та деталь, которую большинство стартеров не делают.

Пароли, восстановление, MFA

Смена пароля

Доступна в профиле (AUTH_PASSWORD_CHANGE_ENABLED). Требует текущий пароль + новый. После успеха — logoutAll(): все устройства получают 401, пользователь логинится заново с новым паролем.

Forgot password

Флаг AUTH_PASSWORD_FORGOT_ENABLED. Матрица восстановления AUTH_RECOVERY_STRICTNESS:

Email-фактор: 6-значный OTP (тот же механизм, что при регистрации). Шаблоны Elastic Email опциональны — без шаблона уходит plain text из i18n.

UI строится динамически: GET /api/v1/auth/recovery/capabilities возвращает доступные факторы, форма адаптируется.

MFA (TOTP)

Setup, confirm, disable — всё в профиле. Отдельный шаг при логине, если MFA включён. Политика паролей (config/password-policy.ts) — единая для UI и API: индикатор силы, валидация на бэкенде при установке или смене.

Admin recovery

AUTH_ADMIN_ACCOUNT_RECOVERY_ENABLED — администратор может сбросить MFA пользователя и установить новый пароль. Security audit фиксирует такие действия.

Сессии и устройства

Каждая сессия — документ RefreshToken с metadata:

• deviceLabel — «Firefox · macOS» из User-Agent

• loginAt / lastSeenAt / expiresAt

• isCurrent — текущее устройство

Пользователь видит список устройств в профиле (AUTH_SESSIONS_ENABLED), может выйти с конкретного устройства или со всех других. Текущее устройство — только через общий «Выйти». Администратор видит полный IP и User-Agent и может отозвать любую сессию.

Онбординг

Два слоя.

Wizard после логина — модалка показывается один раз на браузер (localStorage + версия ONBOARDING_VERSION). Шаги: профиль → MFA → push. На шаге push — iOS PWA hint и кнопка подписки.

Чеклист в профиле — карточка с незавершёнными шагами, не исчезает до явного «Больше не показывать». Кнопки скроллят к соответствующим блокам в профиле — без бессмысленных редиректов.

При bump ONBOARDING_VERSION wizard можно показать снова всем пользователям — полезно при появлении новых фич.

Контент-платформа

Редактор и публикация

Многошаговый редактор: Preview → Content → SEO → Publish. Черновики через ревизии — правите, не затрагивая опубликованную версию. Медиа через Uploadcare: paste/drop в редакторе, responsive <picture> на публичных страницах.

При публикации — IndexNow и Google Search Console уведомляются автоматически. Sitemap и RSS подтягивают только опубликованные публичные статьи из MongoDB.

Безопасность контента

Серверная санитизация HTML после рендера Tiptap через DOMPurify — allowlist тегов и атрибутов, блок опасных URL (javascript:, data:). Unit-тесты на XSS-пейлоады в CI.

Приватные статьи

Видимость PUBLIC / PRIVATE. Приватные статьи поддерживают списки разрешённых ролей — можно сделать «только для ADMIN», «только для EDITOR» и т.д.

Кэш

unstable_cache + revalidateTag на публикацию и обновление ревизии. Публичные страницы быстрые без лишних запросов к БД на каждый hit.

SEO и AI-агенты

Metadata и JSON-LD

На главной: Organization, WebSite, FAQPage, опционально Person и SoftwareApplication. На статьях: Article, BreadcrumbList, author byline. Всё управляется из config/product.ts — author: null скрывает byline и Person schema без изменений в коде.

Группы переводов статей → автоматические hreflang alternates. Canonical URL нормализуется единым util.

AI-friendly delivery

Публичные статьи поддерживают content negotiation:

GET /article/{slug}
Accept: text/markdown  →  Markdown + YAML front matter
Accept: text/html      →  обычная HTML-страница

Заголовки Content-Signal и x-markdown-tokens (примерное количество токенов). Правильный Vary: Accept для CDN.

public/llms.txt — подсказки для LLM-краулеров с полным описанием стека, фич, путей в кодовой базе и инструкцией для AI-агентов, помогающих настраивать форки.

Трекинг AI-referrals: /admin/ai-referrals показывает трафик, пришедший от LLM-агентов через llms.txt.

Push-уведомления

Web Push API с service worker. VAPID_* переменные, подписки хранятся в БД, публичный DTO не отдаёт полный endpoint.

Платформенные события (NOTIFY_*): новый логин, смена/сброс пароля, MFA-события, новые статьи. Для каждого события отдельный флаг и каналы (web_push, email, all).

iOS Safari: NEXT_PUBLIC_PUSH_IOS_PWA_HINT_ENABLED — подсказка «Добавить на экран Домой» в профиле и в онбординге.

LLM в редакторе

Опционально, за NEXT_PUBLIC_LLM_ENABLED=true и LLM_API_KEY на сервере (ключ никогда не попадает в клиент):

• Chat — потоковый ассистент в контексте статьи

• SEO / preview suggest — структурированные подсказки по metadata

• Content suggest — варианты продолжения или переформулировки

• Article audit — разбор черновика в JSON-mode

• Image generate — GPT Image models (allowlist в env)

• Listen audio — TTS для публичных статей

Rate limit per-user (Redis или memory). Дашборд использования: /admin/llm-usage — токены, стоимость по модели и по статье.

Наблюдаемость и админка

Профиль пользователя в админке: роль, статус, push-подписки, активные сессии с revoke, account recovery, security audit по конкретному пользователю.

RUM — Core Web Vitals (LCP, INP, CLS) из реальных сессий, с sampling и cookie consent.

Новый интерфейс: лендинг и статьи

В v0.2 полностью переработан публичный интерфейс демо-сайта.

Лендинг

Отдельный LandingLayout с sticky хедером (логотип NSB + навигация + CTA). Секции: Hero с градиентным акцентом и tech-бейджами стека, Features в виде сетки карточек, QuickStart «4 шага от fork до pnpm dev», ArticlesPreview, FAQ accordion, Footer.

Логотип NSB — SVG-компонент с поддержкой тёмной/светлой темы, используется в хедере лендинга, в сайдбаре кабинета (с ссылкой на главную), в футере.

Статьи

Страница /articles — новый лейаут: крупный заголовок, pill-фильтры сортировки, сетка 3 колонки на десктопе. Карточки статей — border-card с aspect-[16/9] cover-изображением, hover-анимацией thumbnail, line-clamp.

Деталка статьи — ArticleReadingShell: breadcrumb, h1-заголовок, мета-полоса (автор / дата / listen audio), thumbnail как hero-image через next/image fill, тело с prose prose-neutral dark:prose-invert, кнопка «← Articles».

Один и тот же ArticleReadingShell используется для публичных, приватных и preview-статей. Приватные получают amber-бейдж «🔒 Private», preview — violet-бейдж «👁 Preview mode».

Все страницы статей используют LandingLayout вместо устаревшего PreviewUniversalLayout — единая навигация по всему сайту.

Конфигурация и DX

Три уровня настроек

config/product.ts       → название, автор, PWA, marketing links, JSON-LD toggles
config/env.ts           → секреты и feature flags
src/constants/routes.ts → маршруты + SEO (sitemap, breadcrumbs)

pnpm doctor

pnpm doctor        # проверка .env.local
pnpm doctor:prod   # проверка .env.prod

Скрипт проверяет: JWT secret, Mongo URI, MFA key, соответствие email/registration/password флагов, VAPID, LLM key, HTTPS в site URL — и подсказывает что не заполнено.

Claude setup skill

Для пользователей Cowork доступен скилл /setup-nsb — интерактивный wizard, который читает текущий config/product.ts, задаёт вопросы и записывает изменения в файл. Шаги: product identity → env variables → auth mode → AI features → push → media.

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

Типичный набор флагов для production

AUTH_PASSWORD_CHANGE_ENABLED=1
AUTH_PASSWORD_FORGOT_ENABLED=1
AUTH_SESSIONS_ENABLED=1
AUTH_ADMIN_ACCOUNT_RECOVERY_ENABLED=1
ONBOARDING_ENABLED=1
NEXT_PUBLIC_ONBOARDING_ENABLED=1
NOTIFY_LOGIN_ENABLED=1
NOTIFY_PASSWORD_ENABLED=1
EMAIL_SEND_MODE=elastic
EMAIL_API_KEY=...

Push, LLM, Redis — опционально. Выключенное не тормозит — просто не работает.

Деплой

• GitHub Actions — stage и prod pipeline.

• Docker — приложение, MongoDB, Redis, nginx, certbot (Let's Encrypt).

• Мониторинг — Prometheus, Grafana, Loki (опциональный стек, задокументирован).

Документация: docs/INFRASTRUCTURE_PLAN_RU.md, docs/FAQ_RU.md.

Инфраструктура в v0.2 не менялась — только продуктовый функционал и DX.

Чего здесь нет

Явно вне scope:

• Stripe и биллинг — платежи не включены, придётся добавлять.

• OAuth (Google, GitHub) — в roadmap v0.3, сейчас только email+password.

• Multi-tenant — изоляция данных по организациям не встроена.

• PostgreSQL / Prisma — только MongoDB; при форке слой данных можно заменить, но это работа.

• mustChangePassword — после admin-сброса пароля пользователь не обязан сменить пароль при следующем логине (запланировано).

Это не недостатки — это честные границы. Если вам нужен Stripe и OAuth прямо сейчас, ShipFast или Supastarter закроют это быстрее. NSB — для тех, кому важен полный контроль и self-hosted без vendor lock-in.

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

# 1. Fork и клон
git clone https://github.com/Fedorrychkov/nextjs-super-boilerplate

# 2. Установка
pnpm install

# 3. Окружение
cp .env.example .env.local
# заполните JWT_SECRET, MONGO_URI, NEXT_PUBLIC_SITE_URL

# 4. Проверка
pnpm doctor

# 5. Брендинг
# Откройте config/product.ts — название, автор, ссылки

# 6. Запуск
make up-local   # поднять MongoDB локально
pnpm dev:local

Первый admin — через FIRST_ADMIN_LOGIN / FIRST_ADMIN_PASSWORD в env, или вручную в БД.

Подробнее: docs/GETTING_STARTED.md.

Итог

NSB v0.2 — это не «ещё один стартер с login form». Это platform-starter:

• Auth с правильным revoke (sid в JWT, мгновенный 401)

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

• CMS с черновиками, SEO, hreflang, AI-friendly delivery

• Push, audit log, RUM, LLM-редактор — всё за feature flags

• Один файл брендинга, один pnpm doctor, понятная документация

Если вы поднимаете свой продукт на своём сервере и не хотите месяцами собирать security + content + SEO по кусочкам — это база, которую можно включать по частям и доводить до production без сюрпризов.

Issues и обратная связь: github.com/Fedorrychkov/nextjs-super-boilerplate/issues