Next.js Super Boilerplate v0.2: security layer, account management, and AI-ready out of the box

Version: 0.2.0 · June 2026
Repository: github.com/Fedorrychkov/nextjs-super-boilerplate
Demo: nextjs-super-boilerplate.visn-ai.io

When you launch a Next.js product solo or with a small team, the first weeks rarely go to the product itself. They go to auth, password reset, figuring out why session revocation doesn't actually work until the access token expires, wiring up SEO, Docker, CI — and then repeating a version of this on the next project.

Next.js Super Boilerplate (NSB) is an attempt to solve these problems once, correctly, and give developers (and vibe-coders with AI assistants) a production-ready starting point.

v0.2 is not cosmetic. It's a full security and account layer built on top of the working v0.1 base.

Table of contents

• Who it's for

• Stack and principles

• What's new in v0.2

• Auth: why this is different

• Passwords, recovery, MFA

• Sessions and devices

• Onboarding

• Content platform

• SEO and AI agents

• Push notifications

• LLM in the editor

• Observability and admin

• New UI: landing and articles

• Configuration and DX

• Deploy

• What's not included

• Quick start

Who it's for

NSB is a self-hosted starter. You bring your own MongoDB, your own server, your own domain. No vendor lock-in, no hidden infrastructure costs.

Good fit if you need to:

• ship a product with user accounts, roles, and content — fast, without reinventing wheels;

• run a public blog or knowledge base with proper SEO;

• have CI/CD, Docker, and monitoring out of the box;

• work with an AI assistant (Claude, Cursor) — the codebase follows consistent patterns that LLMs read well.

Not a great fit for: Stripe, multi-tenant SaaS, hosted deploy without your own server — you'd need to build those on top.

Stack and principles

Four architectural principles:

1. **Feature flags in `config/env.ts`** — enable only what you need; everything optional is off by default.

2. **One branding file: `config/product.ts`** — name, author, links, PWA, JSON-LD.

3. **Thin routes** — business logic lives in services and server actions, not in route handlers.

4. **Server secrets stay on the server** — JWT, LLM API key, email — never shipped to the client.

What's new in v0.2

v0.1 delivered the base: auth, CMS, SEO, deploy, LLM editor. v0.2 closes the gaps that every production product needs but almost no starter ships.

Auth: why this is different

Most JWT boilerplates have a fundamental flaw: you revoke the refresh token, but the access token stays valid for another hour. The user is technically logged out, but the API keeps returning 200.

NSB solves this properly. The access JWT includes a sid field — the identifier of the RefreshToken document in the database. Every authenticated request runs a middleware check that this session still exists and hasn't been revoked.

Revoke a session = immediate 401. No waiting, no race conditions, no "well, it'll expire eventually."

This isn't rocket science, but it's the detail most starters skip.

Passwords, recovery, MFA

Password change

Available in the user profile (AUTH_PASSWORD_CHANGE_ENABLED). Requires the current password plus the new one. On success — logoutAll(): all devices receive 401 and the user logs in fresh with the new password.

Forgot password

Flag: AUTH_PASSWORD_FORGOT_ENABLED. The recovery matrix is controlled by AUTH_RECOVERY_STRICTNESS:

Email factor: 6-digit OTP (the same mechanism as registration). Elastic Email templates are optional — without a template, plain text from i18n is sent.

The UI builds itself dynamically: GET /api/v1/auth/recovery/capabilities returns available factors, the form adapts.

MFA (TOTP)

Setup, confirm, disable — all in the user profile. Separate login step when MFA is active. Password policy (config/password-policy.ts) is unified across UI and API: strength indicator, server-side validation on set or change.

Admin recovery

AUTH_ADMIN_ACCOUNT_RECOVERY_ENABLED — an admin can reset a user's MFA and set a new password. The security audit log records these actions.

Sessions and devices

Each session is a RefreshToken document with metadata:

• deviceLabel — "Firefox · macOS" parsed from User-Agent

• loginAt / lastSeenAt / expiresAt

• isCurrent — whether this is the active device

Users see their device list in the profile (AUTH_SESSIONS_ENABLED) and can log out from a specific device or from all others. The current device exits only via the main Logout. Admins see full IP and User-Agent and can revoke any session.

Onboarding

Two layers.

Post-login wizard — a modal shown once per browser (localStorage + ONBOARDING_VERSION). Steps: profile → MFA → push. The push step includes an iOS PWA hint and a subscription button.

Profile checklist — a card with incomplete steps that stays visible until the user explicitly dismisses it. Buttons scroll to the relevant section of the profile page — no pointless redirects.

Bumping ONBOARDING_VERSION re-shows the wizard to all users — useful when new features ship.

Content platform

Editor and publishing

Multi-step editor: Preview → Content → SEO → Publish. Drafts via revisions — edit without touching the published version. Media via Uploadcare: paste/drop in the editor, responsive <picture> on public pages.

On publish — IndexNow and Google Search Console are notified automatically. Sitemap and RSS include only published public articles from MongoDB.

Content security

Server-side HTML sanitization after Tiptap rendering via DOMPurify — tag and attribute allowlist, block of dangerous URLs (javascript:, data:). XSS payload unit tests in CI.

Private articles

Visibility: PUBLIC / PRIVATE. Private articles support allowed-role lists — you can restrict to ADMIN, EDITOR, or any combination.

Caching

unstable_cache + revalidateTag on publish and revision update. Public pages are fast without unnecessary DB hits on every request.

SEO and AI agents

Metadata and JSON-LD

Home page: Organization, WebSite, FAQPage, optionally Person and SoftwareApplication. Articles: Article, BreadcrumbList, author byline. Everything is controlled from config/product.ts — author: null removes the byline and Person schema with no code changes.

Translation groups → automatic hreflang alternates. Canonical URLs normalized by a shared utility.

AI-friendly delivery

Public articles support content negotiation:

GET /article/{slug}
Accept: text/markdown  →  Markdown + YAML front matter
Accept: text/html      →  standard HTML page

Content-Signal and x-markdown-tokens headers (approximate token count). Correct Vary: Accept for CDN.

public/llms.txt — hints for LLM crawlers with a full description of the stack, features, key source paths, and instructions for AI agents helping developers set up forks.

AI referral tracking: /admin/ai-referrals shows traffic arriving from LLM agents via llms.txt.

Push notifications

Web Push API with service worker. VAPID_* env variables, subscriptions stored in DB, the public DTO never exposes the full endpoint.

Platform events (NOTIFY_*): new login, password change/reset, MFA events, new articles. Each event has its own flag and channels (web_push, email, all).

iOS Safari: NEXT_PUBLIC_PUSH_IOS_PWA_HINT_ENABLED — "Add to Home Screen" prompt in the profile and in onboarding.

LLM in the editor

Optional, behind NEXT_PUBLIC_LLM_ENABLED=true and LLM_API_KEY on the server (the key never reaches the client):

• Chat — streaming assistant in the context of an article

• SEO / preview suggest — structured metadata suggestions

• Content suggest — continuation or rephrasing options

• Article audit — draft review in JSON mode

• Image generate — GPT Image models (allowlisted in env)

• Listen audio — TTS for public articles

Per-user rate limiting (Redis or memory). Usage dashboard: /admin/llm-usage — tokens and cost by model and article.

Observability and admin

User profile in admin: role, status, push subscriptions, active sessions with revoke, account recovery, security audit per user.

RUM — Core Web Vitals (LCP, INP, CLS) from real sessions, with sampling and cookie consent.

New UI: landing and articles

v0.2 includes a complete redesign of the public interface.

Landing page

A dedicated LandingLayout with a sticky header (NSB logo + nav + CTA buttons). Sections: Hero with gradient accent and stack tech badges, Features card grid, QuickStart "4 steps from fork to pnpm dev", ArticlesPreview, FAQ accordion, Footer.

The NSB logo is an SVG component supporting dark/light themes, used in the landing header, in the dashboard sidebar (linking back to the homepage), and in the footer.

Articles

The /articles page has a new layout: large heading, pill-style sort filters, 3-column grid on desktop. Article cards are border-cards with aspect-[16/9] cover images, thumbnail hover animation, and line-clamp.

The article detail page uses ArticleReadingShell: breadcrumb, h1 heading, meta bar (author / date / listen audio), thumbnail as a hero image via next/image fill, body with prose prose-neutral dark:prose-invert, "← Articles" back link.

The same ArticleReadingShell is shared across public, private, and preview article pages. Private articles get an amber "🔒 Private" badge; preview gets a violet "👁 Preview mode" badge.

All article pages now use LandingLayout instead of the old PreviewUniversalLayout — unified navigation across the entire site.

Configuration and DX

Three levels of configuration

config/product.ts       → name, author, PWA, marketing links, JSON-LD toggles
config/env.ts           → secrets and feature flags
src/constants/routes.ts → routes + SEO config (sitemap, breadcrumbs)

pnpm doctor

pnpm doctor        # validate .env.local
pnpm doctor:prod   # validate .env.prod

The script checks: JWT secret, Mongo URI, MFA key, consistency between email/registration/password flags, VAPID keys, LLM key, HTTPS in site URL — and tells you what's missing.

Claude setup skill

For Cowork users, the /setup-nsb skill provides an interactive wizard that reads your current config/product.ts, asks questions, and writes the changes. Steps: product identity → env variables → auth mode → AI features → push → media.

Documentation

Typical production flag set

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 — optional. Disabled features don't slow anything down — they simply don't run.

Deploy

• GitHub Actions — stage and prod pipelines.

• Docker — app, MongoDB, Redis, nginx, certbot (Let's Encrypt).

• Monitoring — Prometheus, Grafana, Loki (optional stack, documented).

Infrastructure docs: docs/INFRASTRUCTURE_PLAN_RU.md, docs/FAQ_RU.md.

The infrastructure layer didn't change in v0.2 — only the product functionality and DX did.

What's not included

Explicitly out of scope:

• Stripe and billing — payments are not included, you'd need to add them.

• OAuth (Google, GitHub) — roadmap for v0.3, currently email+password only.

• Multi-tenancy — per-organization data isolation is not built in.

• PostgreSQL / Prisma — MongoDB only; the data layer can be replaced in a fork, but it's real work.

• mustChangePassword — after an admin password reset, users aren't forced to change on next login (planned).

These are honest boundaries, not shortcomings. If you need Stripe and OAuth right now, ShipFast or Supastarter will get you there faster. NSB is for those who want full control and self-hosted without vendor lock-in.

Quick start

# 1. Fork and clone
git clone https://github.com/Fedorrychkov/nextjs-super-boilerplate

# 2. Install
pnpm install

# 3. Environment
cp .env.example .env.local
# fill in JWT_SECRET, MONGO_URI, NEXT_PUBLIC_SITE_URL

# 4. Validate
pnpm doctor

# 5. Branding
# Open config/product.ts — set name, author, links

# 6. Run
make up-local   # start MongoDB locally
pnpm dev:local

First admin — set via FIRST_ADMIN_LOGIN / FIRST_ADMIN_PASSWORD in env, or create manually in the DB.

Full guide: docs/GETTING_STARTED.md.

Summary

NSB v0.2 is not "another starter with a login form." It's a platform-starter:

• Auth with proper revoke (sid in JWT, immediate 401)

• Full account recovery with a multi-factor matrix

• CMS with drafts, SEO, hreflang, AI-friendly delivery

• Push, audit log, RUM, LLM editor — all behind feature flags

• One branding file, one pnpm doctor, clear documentation

If you're shipping your product on your own server and don't want to spend months assembling security + content + SEO piece by piece — this is a base you can enable incrementally and take to production without surprises like "session revoked but the API still returns 200 for another hour."

Issues and feedback: github.com/Fedorrychkov/nextjs-super-boilerplate/issues