Features
- Next.js 16 — App Router, Turbopack, React 19, React Compiler
- TypeScript — strict mode (
noUncheckedIndexedAccess, exactOptionalPropertyTypes)
- Tailwind CSS v4 — CSS-first config, oklch design tokens, shadcn/ui components
- i18n — next-intl,
[locale] routing, key-parity check, typed messages, title template + hreflang
- State — Redux Toolkit (live
uiSlice example) + TanStack Query (streaming SSR: pending-query dehydration + useSuspenseQuery)
- Forms — React Hook Form + shared Zod schema, re-validated in a Server Action
- Security — per-request CSP nonce (
strict-dynamic), hardened headers, one rate-limit identity rule for pages/API/actions, CSRF check for actions, header-only ISR webhook secret
- Quality gates — ESLint (0 warnings), Stylelint, Prettier, typecheck (app + tests), Vitest 5, i18n parity, knip, commitlint —
pnpm check runs them all; CI and Vercel run the same set
- Supply chain — pnpm
minimumReleaseAge + install-script allow-list, SHA-pinned Actions, Dependabot cooldown
Quick Start
npx degit hHolyMolly/next-template my-app
cd my-app
pnpm install
git init && pnpm prepare # enable git hooks
pnpm dev
Remove the demo surface when you start building:
pnpm clean:demo my-app # degit clones: also renames + finalizes
pnpm clean:demo my-app --force # git clones: force the finalization step
Node.js 24+, pnpm 10.16+. next-env.d.ts is generated by pnpm dev / pnpm typecheck.
Living Examples (removed by clean:demo)
Every shipped library is exercised by real code on the home page:
| Example | Shows |
|---|
[locale]/components/ContactForm | RHF + zodResolver → Server Action (withServerAction + CSRF + rate limit) → toast |
[locale]/components/HealthStatus | TanStack Query streaming SSR: in-process prefetch + HydrationBoundary → useSuspenseQuery + ErrorBoundary; axios refetches |
[locale]/components/DemoBanner | Redux uiSlice + featureFlags + useLocalStorage |
GET /api/health · POST /api/echo | withApiHandler: Zod validation, typed errors, rate-limit headers |
Commands
| Command | Description |
|---|
pnpm dev / build / start / preview | Develop · build · serve |
pnpm lint / lint:fix | ESLint, 0 warnings allowed |
pnpm lint:css / lint:css:fix | Stylelint check · autofix |
pnpm format / format:check | Prettier write · check |
pnpm typecheck / typecheck:test | TypeScript: app · tests |
pnpm test / test:watch / test:coverage | Vitest (+ coverage thresholds) |
pnpm check | All gates in one command (same set as CI) |
pnpm check:i18n | Locale key parity |
pnpm knip | Unused files / deps (blocking), exports (advisory) |
pnpm analyze | Turbopack bundle analyzer |
pnpm clean / clean:cache / clean:demo | Cleanup |
Git hooks: pre-commit (lint-staged + i18n parity) · commit-msg (commitlint) · pre-push (typecheck + tests).
Project Structure
src/
├── app/
│ ├── layout.tsx # <html>/<body>, JSON-LD (nonce), styles, font variable
│ ├── api/ # health · echo (demo) · revalidate (ISR webhook) — withApiHandler
│ └── [locale]/
│ ├── layout.tsx # locale + NextIntlClientProvider (client namespaces)
│ ├── page.tsx # demo home (SSR query prefetch)
│ ├── components/ # demo surface (clean:demo removes it)
│ └── (routes)/ # Header/Footer layout, template page, 404 catch-all
├── components/ UI/ (shadcn) · layouts/ (Header, Footer, LanguageSwitch, WebVitals, …) · icons/
├── configs/ project · metadata · routes · env · featureFlags
├── hooks/ 13 SSR-safe hooks
├── lib/ withApiHandler · withServerAction · rateLimit · errors · errorReporting · cn · queryClient
├── messages/ {en,ru}/{translations,metadata,demo}.json
├── services/ api (http policy · axios · serverFetch · queryOptions · cache) · i18n (next-intl)
├── store/ Redux Toolkit (slices/uiSlice)
├── styles/ tailwind.css (@theme) · vars.css (oklch tokens) · normalize.css (@layer base) · fonts.ts
└── proxy.ts middleware: rate limit → CSP nonce → next-intl
Environment
.env.development / .env.production are committed (no secrets). Local overrides go to
.env.local (gitignored, wins). Required: NEXT_PUBLIC_CLIENT_URL. Full list: .env.example.
Deploy
Vercel — import the repo; vercel.json runs pnpm check && pnpm build on every push (same gates as CI).
Self-hosted — pnpm build && pnpm start behind a reverse proxy (set TRUSTED_PROXY_HOPS).
Docs
Architecture rules, conventions and security contracts live in AGENTS.md —
the single source of truth for humans and AI agents alike. Debugging notes: docs/gotchas.md.
Release checks: docs/verification-playbook.md. Security policy: SECURITY.md.
License
MIT © HolyMolly
