DEV Community: Salman Shahriar

Next.js Best Practices in 2026: Why I Built Next-Elite

Salman Shahriar — Tue, 01 Sep 2026 02:55:24 +0000

Every serious Next.js project starts with the same fifteen things that aren't the product: auth, layouts, permissions, env validation, an API client, i18n, UI primitives, SEO, tests, linting, formatting, Docker, CI, error tracking, analytics.

Before I built Next Elite, I did what most people do first: I looked at what already existed. The official starter, the popular free kits, the paid ones. Some of them are genuinely excellent at what they set out to do. None of them fit the specific shape of project I kept building, a role-based SaaS dashboard sitting in front of a backend I don't own, shipped in more than one language.

This post walks through that landscape as it stood in 2026, and then makes the actual case for why Next-Elite is the one I'd hand a developer starting that kind of project today. Not "best" in the abstract. Best for that.

What "best" should mean for a 2026 boilerplate
The 2026 landscape, honestly
Where the gap is
Why Next-Elite fills it
Feature walkthrough
Where Next-Elite is not the answer
Why now, specifically
Get started

1. What "best" should mean for a 2026 boilerplate

"Best Next.js boilerplate" is a search query with hundreds of contradictory answers, because nobody agrees on what's being optimized for. A boilerplate that's best for a solo founder shipping a $20/month tool in a weekend is a bad fit for a team shipping a multi-role SaaS dashboard, and vice versa. So before arguing for anything, here's the criteria I actually think matter in 2026:

Current stack, not last cycle's. Next.js 16 stabilized Turbopack and shipped React 19.2 with real architectural changes underneath (Cache Components, View Transitions). A boilerplate still pinned to Next.js 14 patterns is teaching you yesterday's defaults.
Architectural fit, not architectural maximalism. The best boilerplate isn't the one with the most integrations, it's the one whose assumptions match your project's shape. A kit that bundles Prisma and Postgres is the right answer for a project that wants Next.js to be the whole backend, and the wrong answer for one that already has a backend team.
Security that lives in the right place. 2025's CVE-2025-29927 let attackers skip Next.js middleware entirely with a crafted header, bypassing any auth check that lived only there. A boilerplate built after that lesson should enforce authorization server-side, in Server Components and Route Handlers, not lean on middleware as the only gate.
i18n as a first-class citizen, not an afterthought. Most boilerplates are English-only by default. If your product will ever ship in more than one market, retrofitting i18n later is a much bigger job than building on it from day one.
Tooling that respects your time. Linting and formatting on a large codebase with ESLint alone routinely takes 30 to 60 seconds; Rust-based tooling like Oxlint runs the same checks in a fraction of that.
Cost matching the license. Free-and-open-source is not automatically better than paid, a $199 to $649 one-time SaaS kit that saves you weeks of Stripe and email wiring is a fair trade for a lot of teams. But it should be a deliberate choice, not the only option on the table.

Judged on those six criteria, here's how the landscape actually looks.

2. The 2026 landscape, honestly

I'm not going to pretend the alternatives are bad. They're built for different jobs.

The official Next.js SaaS Starter, maintained by the Next.js team itself, is free, MIT-licensed, and demonstrates the framework's own current best practices. It ships Postgres and Stripe subscriptions with shadcn/ui. It's intentionally minimal: no built-in RBAC, no i18n, no admin dashboard beyond the basics. It's the best free starting point if you want clean foundations and don't mind building the last 40% yourself, which is exactly what it's designed for.

create-t3-app scaffolds a typesafe full-stack app from modular pieces, TypeScript, tRPC, Prisma or Drizzle, NextAuth, Tailwind. It's excellent for learning the typesafe-stack pattern and for smaller full-stack apps where Next.js owns the database. It isn't trying to be a role-based SaaS dashboard kit, and doesn't claim to be.

ixartz's Next.js Boilerplate is the community heavyweight in the free tier: auth, multi-tenancy, roles and permissions, i18n, database migrations, a full Vitest + Playwright testing suite, all MIT-licensed. It's a serious, well-maintained project and a completely reasonable choice if you want the database and multi-tenancy bundled in from the start.

Paid kits like ShipFast and MakerKit solve a different problem: speed to a sellable product. ShipFast bundles Stripe payments, transactional email, and a blog for a one-time fee, straightforward, well-documented, no surprises. MakerKit goes further with a Turborepo monorepo, team accounts, and enterprise features, aimed at teams who'll pay for that scaffolding rather than build it. Building an equivalent foundation from scratch, auth, billing, multi-tenancy, a marketing site, has been estimated at somewhere around $7,500 to $12,000 in developer time, which is exactly the math that makes a $200 to $650 one-time kit an easy yes for a lot of founders.

None of this is a case against any of them. It's the honest starting point for the actual question: what's missing.

3. Where the gap is

Every option above makes the same underlying assumption in one direction or another: either Next.js owns the database (the official starter, T3, ixartz, the paid kits), or you're building something small enough that architecture doesn't matter yet.

Almost none of them assume the opposite, common, situation: you already have a backend, a Go service, a Laravel API, a BFF layer your platform team owns, and you need a frontend that's genuinely good at consuming it, with real role-based access control and real multi-language support, without dragging in a database layer you're going to rip out on day two.

That's the specific gap Next-Elite is built for.

4. Why Next-Elite fills it

Here's the direct comparison, using the same six criteria from section 1:

	Official Next.js Starter	ixartz Boilerplate	ShipFast / MakerKit	Next-Elite
Stack currency	Current	Current	Current	Next.js 16.4, React 19.3, TypeScript 7
Database assumption	Postgres bundled	Postgres/Drizzle bundled	Bundled (Prisma/Postgres)	None, API-driven by design
RBAC	Not included	Roles & permissions	Varies by tier	Permission-based, server-enforced guards
i18n / RTL	Not included	Included (locales vary)	Rare	6 languages, RTL, type-checked keys
Linting	ESLint	ESLint	ESLint	Oxlint + Oxfmt (dramatically faster)
Testing	Minimal	Vitest + Playwright	Varies	Vitest + Playwright, pre-wired
License / cost	Free (MIT)	Free (MIT)	$199 to $649 one-time	Free (MIT)
Best for	Learning current Next.js patterns, small full-stack apps	Full-stack SaaS that wants the DB bundled	Fastest path to a sellable, DB-owning SaaS	Multi-role, multi-language frontends sitting in front of an existing or external API

The columns aren't competing to be "better" in general, they're solving different problems. Next-Elite's column is the one that exists specifically for "the backend isn't Next.js's job here."

5. Feature walkthrough

Auth and RBAC that enforce on the server. BetterAuth handles email/password and Google OAuth. Authorization is separate and deliberate: requireUser() and requirePermission() run inside Server Components, and Next.js parallel routes (@admin, @user) mean role-specific dashboards (dashboard, analytics, profile, settings) don't need runtime branching in the render tree at all. This is the direct, practical answer to the CVE-2025-29927 lesson from section 1: the project has no middleware at all, so nothing security-critical can be skipped at the edge. Roles and their permissions live in one typed file, so a misspelled permission is a compile error. One thing to plan for: with no database configured, BetterAuth uses an in-memory store, which is perfect for the demo but loses users on restart, so connect a database adapter or your own backend's auth before going to production.

const AdminDashboardPage = async () => {
  const [, t] = await Promise.all([
    requirePermission('dashboard.view:admin'),
    getTranslations('dashboard.admin'),
  ]);
  return <h1>{t('title')}</h1>;
};

i18n that's actually type-safe. Six languages, English, Bengali, Arabic (RTL), French, Spanish, Simplified Chinese, via next-intl, cookie-based so there's no /en/ URL prefix to manage. Translation keys are checked at compile time, so a typo'd key fails the build instead of silently rendering blank in production, and a unit test makes sure every locale has the same keys as English. RTL support in particular is something most of the boilerplates in section 2 simply don't ship; Next-Elite's layouts use logical start/end spacing so the same components work in both directions.

Frontend-first, API-driven architecture. No Prisma, no Drizzle, no Postgres. TanStack Query is pre-configured in providers.tsx, ready to point at your REST, GraphQL, or BFF endpoint. Drop it in front of whatever backend already exists. (If you want a matching backend, a companion template, Next Elite Server, with NestJS, BetterAuth, Drizzle ORM, and PostgreSQL, is coming soon.)

50+ shadcn/ui components you own. Built on Tailwind CSS v4 and Radix UI, including stat cards, charts, a sortable and paginated data table, a searchable combobox, and a date picker, with a live /ui-components showcase page. Every color and radius comes from light and dark design tokens, so rebranding or adjusting dark mode is a token change, not a find-and-replace. Because the components are code in your repo rather than an imported library, extending one (a new variant) doesn't mean waiting on someone else's release.

Tooling that doesn't waste your CI minutes. Oxlint and Oxfmt for linting and formatting, Knip for dead code, Lefthook wiring pre-commit, commit-msg, and pre-push hooks so problems get caught before they reach a PR, not during it. Dependencies are pinned to exact versions and kept current by Renovate and Dependabot. And because a lot of 2026 code is written with AI agents, the repo ships its conventions for them too: an AGENTS.md and a project-standards skill that tell Claude Code, Cursor, Codex and friends to reuse existing components, add variants instead of duplicates, and use design tokens only.

Testing from the first commit. Vitest and React Testing Library for units and components, Playwright for the handful of end-to-end flows that matter (including checking that the security headers are actually sent), npm run check as a single CI gate: typecheck, lint, dead code, tests. CI also deletes the demo code on every push and runs the checks again, so npm run demo:remove always leaves you a clean, working app.

Observability, security, and deployment that aren't afterthoughts. Sentry (lazy-loaded, and only when a DSN is set), Vercel Analytics (rendered only on Vercel), and a /api/health endpoint. A strict Content Security Policy, HSTS, and frame protection are set in code. Standalone Docker output on a Distroless base image, with multi-arch builds (amd64/arm64) for self-hosting on ARM, Dokploy-ready, or one click to Vercel.

Performance measured, not assumed. I ran the Turbopack bundle analyzer on the project and moved everything that didn't need to be on every page off the first load: Sentry, the env validation library, and the charting library. That cut first-load JavaScript by 21–24% per page, and the live demo's total transfer went from 906 KB to 462 KB. The project's Lighthouse report shows 100 across Performance, Accessibility, Best Practices, and SEO, plus 3/3 on Agentic Browsing:

All of it, MIT-licensed, free.

6. Where Next-Elite is not the answer

An argument for "best for X" is only credible if it also says what it's not for.

You want the database bundled in. If you want Next.js to be your whole backend, ixartz's boilerplate or the official Next.js SaaS Starter will serve you better than fighting Next-Elite's API-driven assumption.
You want payments and billing pre-wired. Next-Elite doesn't include Stripe. ShipFast or MakerKit will save you more time if billing is core to the MVP.
Your project is small enough that this is overkill. A landing page or a weekend prototype doesn't need feature-based architecture, RBAC, or six languages. create-next-app is the right answer there.
You need enterprise compliance features out of the box. SOC 2 audit logging and SSO aren't in scope here; a kit like Bedrock exists specifically for that.
You need per-locale URLs for SEO. Cookie-based i18n keeps routing simple, but if /es/... pages must rank separately from /en/... pages, you'll need a path-prefixed routing setup that Next-Elite doesn't ship.

If none of those describe your project, and it does involve multiple roles, more than one language, or a backend you don't want to duplicate inside your frontend, that's the project Next-Elite was built for.

7. Why now, specifically

2026 is a reasonable moment to make this call, not an arbitrary one. Turbopack went stable as the default bundler in Next.js 16, React 19.2 shipped View Transitions and the Activity component underneath it, and the framework's own security posture keeps evolving in ways that reward architecture over reflexive middleware checks. A boilerplate built on last cycle's defaults isn't just missing features, it's teaching patterns the framework itself has moved past. Next-Elite is built on Next.js 16.4, React 19.3, and TypeScript 7 for that reason, not as a version-number flex, but because starting a 2026 project on 2024 patterns is a debt you pay down later.

8. Get started

git clone https://github.com/salmanshahriar/Next-Elite.git
cd Next-Elite
npm install
cp .env.example .env
npm run dev

Open http://localhost:6767. Auth, RBAC-gated dashboards, six languages, and everything above is already wired together. When you're ready to build your own product, run npm run demo:remove and npm run check.

Live Demo · GitHub Repo · Use This Template · Deploy on Vercel

If this is the project you keep rebuilding from scratch too, it's free, MIT-licensed, and a star helps more people find it.

Next.js Best Practices in 2026: The Boilerplate I Built So I Stop Repeating Myself

Salman Shahriar — Tue, 01 Sep 2026 02:45:43 +0000

Every serious Next.js project I start needs the same fifteen things before the actual product exists: authentication, layouts, permissions, environment validation, an API client, i18n, UI primitives, SEO metadata, tests, linting, formatting, Docker, CI, error tracking, analytics.

None of that is the product. All of it has to exist before the product can ship.

I kept rebuilding this foundation project after project, and each time I rebuilt it slightly differently, which meant relearning my own past decisions instead of improving on them. So I wrote down what "doing it right" actually means for a Next.js app in 2026, and then built that answer into an open-source boilerplate, Next Elite, so the decision only has to happen once.

This post is that answer. It is not a features list. For each practice I'll explain the problem it solves, where developers disagree about it, and then show concretely how Next-Elite implements it, distinguishing clearly between "this is a 2026 best practice" and "this is a choice I made in my own boilerplate."

If you never touch Next-Elite, the checklist at the end still works as a reference for starting a serious Next.js project in 2026.

What "production-ready" actually means in 2026
Start with architecture, not components
Frontend-first and API-driven architecture
Server Components vs Client Components
Authentication is not authorization
RBAC without scattering permission logic everywhere
TypeScript should enforce architecture, not just describe it
Type-safe internationalization
UI architecture with Tailwind + shadcn/ui
Data fetching: don't turn everything into React state
Environment variables should fail safely
SEO should be part of the architecture
Performance should be a default, not a final optimization
Testing strategy
Code quality is an engineering system
Observability from day one
Docker and deployment should be boring
What I intentionally did NOT include
The trade-offs
The actual boilerplate: Next Elite
Final checklist: my 2026 Next.js project checklist

1. What "production-ready" actually means in 2026

"Production-ready" gets used as a synonym for "has TypeScript, Tailwind, and an auth library." That's not what it means. A project with all three of those can still fall over the first time two developers touch the same file, or the first time someone forgets to set an environment variable in a new deploy target.

In practical terms, production readiness in 2026 means:

Maintainability: a new developer can find where a feature lives without a guided tour.
Type safety that extends past props: config, permissions, translations, and API responses are typed, not just component inputs.
Predictable architecture: the same kind of problem is always solved the same way.
Security boundaries that live on the server: the UI can hide a button; only the server can actually deny a request.
Testing at more than one layer: unit, component, and end-to-end each catch a different class of bug.
Observability before the incident: error tracking and health checks exist before you need them, not after the first outage.
A deployment story that doesn't force a rewrite: whether that's Vercel or your own Docker host.
Performance and SEO as defaults, not a pre-launch checklist item.

None of these require exotic tools. Most of them require deciding early and enforcing the decision consistently, which is a cultural problem as much as a technical one.

2. Start with architecture, not components

The default Next.js tutorial structure looks like this:

src/
  components/
  hooks/
  utils/
  app/

This works until it doesn't. Once a project has more than a handful of screens, "components" stops meaning anything: it holds unrelated UI for auth, billing, and settings side by side, and touching one feature means opening files scattered across four folders. Notably, Next.js's own documentation doesn't mandate a single structure; the framework explicitly supports colocating by route, splitting by feature, or keeping a flat top-level layout, and leaves the choice to the team. There is no "correct" Next.js folder structure handed down by the framework, which is exactly why so many teams land on the same fix independently: group code by feature, not by file type.

Next-Elite structures its domain logic under src/features/, where each feature owns its own hooks, schemas, server helpers, and types:

src/features/
├── auth/
│   ├── lib/          # BetterAuth server + auth-client singletons
│   ├── server/       # Server-only helpers (getCurrentUser)
│   ├── hooks/        # Auth provider + useAuth hook
│   ├── rbac/         # permissions, roles, can, require
│   ├── schemas/      # Zod login + register schemas
│   └── types.ts
├── i18n/              # next-intl config (routing, request, locale actions, RTL hook)
└── site/              # site.config.json, its schema, server-only base URL, locale helpers

Shared, feature-agnostic UI still lives centrally, under src/components/ (ui/ primitives, shared/ app pieces, layout/ shell, icons/), because forcing genuinely reusable building blocks into a feature folder just relocates the mess instead of solving it. The rule Next-Elite follows is: if it's about one feature, it lives in that feature's folder; if it's used by every feature, it's shared.

Demo code gets the same treatment: the landing page, the component showcase, and the demo accounts all live in one src/_demo(DELETE)/ folder, and npm run demo:remove deletes it and rewrites every file that referenced it. CI runs that removal on every push, so "delete the demo" never turns into an afternoon of chasing broken imports.

When this is worth it: SaaS apps with multiple roles, dashboards with several independent domains (billing, users, settings), or any project a second developer will touch in six months.

When it's over-engineering: a landing page, a five-screen MVP, or a prototype you'll throw away in a month. Feature folders for a project with one feature is just extra typing.

3. Frontend-first and API-driven architecture

This is the architectural decision Next-Elite is built around, and it's the one most likely to get pushback, so it deserves the most honest treatment.

Most Next.js boilerplates assume the framework owns the whole stack: Prisma or Drizzle, a Postgres instance, an ORM schema tightly coupled to the UI. That's a completely reasonable choice for a small product where Next.js genuinely is the backend. It is a much worse fit the moment you already have a backend team, an existing service in Go or Laravel, or a plan to eventually ship a mobile client against the same API.

Next-Elite deliberately does not own a database. It's built to sit on top of whatever you already have, REST, GraphQL, or a BFF layer, and treats TanStack Query as the seam between the frontend and that backend. The trade-off is explicit:

	Frontend owns the DB (Next.js as full stack)	Frontend is API-driven (Next-Elite's approach)
Best for	Solo builder, single client, fastest path to a working app	Existing backend, multiple clients, a team that owns the API separately
Cost	Fewer moving parts, one deploy	An API contract to define and maintain
Risk	Frontend and backend rewrite together if you ever split them	None, but you're doing more upfront wiring
Mobile/second client later	Usually means duplicating backend logic	Already speaks the same API

Neither option is "more architecturally correct." The mistake is picking the database-coupled path by default and discovering the coupling problem only after the product needs a second client or a separate backend team. Next-Elite's stance is: decide this on purpose, and if you decide you want the database bundled in, it isn't the right starting point for you, several other well-known Next.js starters (ones that ship Prisma, Postgres, and multi-tenancy out of the box) solve that problem well and are worth using instead. (For the backend side, I'm also building a companion template, Next Elite Server, with NestJS, BetterAuth, Drizzle ORM, and PostgreSQL. It's coming soon.)

4. Server Components vs Client Components

Recommended practice: default to Server Components for everything, and only add 'use client' at the smallest possible boundary, a button, a form, a toggle, not an entire page. Next.js 16's App Router still renders Server Components first; the client boundary is where interactivity, browser APIs, or local state actually live. This isn't a style preference so much as a bundle-size decision: every client component is JavaScript the browser has to download, parse, and hydrate, and the newer primitives React 19.2 introduced (View Transitions, useEffectEvent, <Activity>, shipped as part of the Next.js 16 line) all assume this server-first default rather than replacing it.

How Next-Elite handles it: the request lifecycle is intentionally linear. A page renders as a Server Component first, requireUser() / requirePermission() check the session there, translations are resolved server-side via next-intl, and only the interactive parts (forms, the theme toggle, the query-backed lists) cross into 'use client':

flowchart TB
    User([User]) --> Page

    subgraph Server["Server (runs first)"]
        Page[Page / Layout]
        Guard["requireUser() / requirePermission()"]
        Page --> Guard
        Guard -->|reads session + role| Auth[BetterAuth]
    end

    subgraph Client["Client (runs in browser)"]
        Hook["useQuery (TanStack Query)"]
        Hook -->|fetch| Api["Your backend API"]
    end

    Page -->|sends HTML| User
    Page -.->|interactive parts| Hook

The practical rule Next-Elite's structure encodes: if a component needs useState, an event handler, or a browser API, it's a client component. If it just needs data and permission, it stays on the server. The boundary also matters for what crosses it: server-only values are passed down as props instead of imported into client code. For example, the "Google sign-in enabled" flag is read from the validated env on the server and handed to the auth provider, so the env validation library never ends up in the browser bundle.

5. Authentication is not authorization

These get conflated constantly, and the conflation is where security bugs come from.

Authentication answers: who are you?
Authorization answers: what are you allowed to do, now that I know who you are?

A login form is authentication. A dashboard that only admins can see is authorization. Treating "the user is logged in" as sufficient to gate an admin page is a common and avoidable mistake.

There's also a sharper, more recent lesson here. In 2025, a critical Next.js vulnerability (CVE-2025-29927) let attackers send a specific header and skip middleware entirely, bypassing any authentication checks that lived only in middleware. The deeper lesson wasn't "patch your dependencies" (although do that too), it was architectural: middleware is not a security boundary. It's an edge layer meant for routing and response shaping, not the last line of defense. Real authorization checks have to live in your Server Components, Route Handlers, and Server Actions, where they can't be skipped by a crafted request.

Recommended practice: authenticate however fits your product (email/password, OAuth, passkeys), but authorize on the server, close to the data, every time, not once in middleware and never again.

How Next-Elite handles it: authentication is BetterAuth, wired for email/password and Google OAuth through /api/auth/* route handlers, with admin emails configurable via the server-only AUTH_ADMIN_EMAILS variable. Authorization is separate and server-side, and the project has no middleware at all, so there's no edge layer to bypass:

// Server Component example
import { requirePermission } from '@/features/auth/rbac/require';
import { getTranslations } from 'next-intl/server';

const AdminDashboardPage = async () => {
  const [, t] = await Promise.all([
    requirePermission('dashboard.view:admin'),
    getTranslations('dashboard.admin'),
  ]);
  return <h1>{t('title')}</h1>;
};

export default AdminDashboardPage;

requirePermission runs in the Server Component itself and redirects to /login (no session) or /unauthorized (no permission) before any protected content renders. One limitation to know before you deploy: with no database configured, BetterAuth falls back to its built-in in-memory store. That's ideal for the demo and local development, but users and sessions are lost on restart and aren't shared between server instances, so production needs a real database adapter (or auth pointed at your own backend). The project's production checklist calls this out explicitly.

6. RBAC without scattering permission logic everywhere

Recommended practice: roles and permissions should be defined in one place, checked through a small set of functions, and never re-implemented as ad hoc if (user.role === 'admin') checks scattered through components. Scattered checks are how a permission gets forgotten on the one page nobody remembered to update.

It's also worth being honest that RBAC is not always the right amount of complexity. A single-tenant internal tool with one kind of user needs an authentication check, full stop. RBAC earns its cost when a product has genuinely different classes of users with different capabilities, not by default.

How Next-Elite handles it: RBAC is deliberately simple, two roles (user, admin) with permission strings, checked through requireUser() and requirePermission() on the server, plus Next.js parallel routes so role-specific layouts don't need runtime branching in the render tree at all. Both roles share the same URLs, and the layout mounts the right slot:

src/app/(protected)/
  ├── @admin/               # Admin slots (dashboard, analytics, profile, settings)
  ├── @user/                # User slots (dashboard, analytics, profile, settings)
  ├── unauthorized/         # Shown when a role lacks permission
  └── layout.tsx            # Picks slot based on permissions

Adding a role is a three-step, explicit process: extend the UserRole union in permissions.ts, map its permissions in ROLE_PERMISSIONS in the same file, and optionally add a parallel route slot. It intentionally does not attempt multi-tenant, hierarchical, or resource-scoped permissions; for complex multi-tenant permission graphs, that logic belongs on your main API, not bolted onto a frontend starter. The UI can still hide a disabled button for a role that lacks a permission (useAuth().hasPermission() exists for exactly that), which is good UX, but the enforcement that matters happens in requirePermission, on the server, where a hidden button can't be bypassed by editing the DOM.

7. TypeScript should enforce architecture, not just describe it

Recommended practice: TypeScript's value in 2026 isn't "the compiler catches typos." It's using the type system to make invalid states hard to represent at all, typed config, typed environment variables, typed permission strings, typed translation keys, so an entire category of runtime bug turns into a compile-time error instead.

How Next-Elite handles it: this shows up in four concrete places rather than as a slogan:

Environment variables are validated and typed through T3 Env (src/libs/env.ts), so a malformed value, like an NEXT_PUBLIC_APP_URL that isn't a URL or a BETTER_AUTH_SECRET shorter than 32 characters, fails loudly at startup instead of surfacing as a broken feature later.
Translation keys are type-checked through next-intl; t('dashboard.title') only compiles if that key exists in messages/en.json, so a typo'd key fails the build instead of silently rendering nothing.
RBAC permissions are a typed union (UserRole and AuthPermission in permissions.ts), so requirePermission('dashbord.view:admin'), misspelled, is a type error, not a bug that ships and gets discovered by a user with too much access.
Site config has a Zod schema that defines its type, and a unit test validates site.config.json against it, so the config is typed in the editor and checked in CI without shipping the validator to the browser.

TypeScript 7 in strict mode (with noUncheckedIndexedAccess) across the codebase is table stakes; the part that actually prevents bugs is using types to encode business rules (valid roles, valid locales, valid config shape), not just typing function signatures.

8. Type-safe internationalization

Recommended practice: i18n bolted on at the end of a project usually means hardcoded strings scattered through components, a hunt-and-replace refactor, and a translation key system with no compile-time safety, so a typo'd key just renders blank in production. It also usually means nobody thought about RTL languages until a customer in an Arabic-speaking market asks why the layout is broken. RTL isn't a CSS afterthought, it changes how you think about "start" and "end" instead of "left" and "right" throughout the component tree, which is much cheaper to design in from the start than to retrofit.

How Next-Elite handles it: next-intl provides cookie-based locale switching (a NEXT_LOCALE cookie set by a Server Action, no /en/ or /es/ URL prefix) across six languages, including Arabic with RTL support, and translation keys are type-checked against messages/en.json at compile time. A unit test also checks that every locale file has exactly the same keys as English, so a missing translation fails CI. Layout code uses logical utilities (ms-*/me-*, ps-*/pe-*, border-e) instead of left/right, so the same components work in both directions. Adding a language is three steps: add the locale to site.config.json, create messages/<locale>.json, and the runtime and types pick it up automatically.

The trade-off is explicit: cookie-based locale means simpler routing, but it has two costs. First, if you need path-prefixed URLs for per-locale SEO indexing (/es/dashboard ranking separately from /en/dashboard), that requires a custom router setup Next-Elite doesn't provide out of the box. Second, because the server has to read the cookie to know the language, public pages render on every request instead of being statically cached at the CDN. For an app that lives mostly behind a login, that's the right call; for a large multilingual marketing site, it's a real limitation to know about before you start.

9. UI architecture with Tailwind + shadcn/ui

Recommended practice: treat shadcn/ui as a foundation you own and edit, not a component library you import and never touch. Its actual value in 2026 isn't the number of components available, it's that the code lives in your repo, built on accessible Radix primitives with Tailwind and CVA for variants, so you can change a button's behavior without fighting a black-box dependency's API surface. The second half of the practice is a design system underneath it: colors, radii, and spacing come from tokens, never from hard-coded hex values, so dark mode and rebranding are a token change instead of a find-and-replace.

How Next-Elite handles it: the boilerplate ships 50+ of these primitives and custom components under src/components/ui/, including stat cards, an area chart, a sortable and paginated data table, a searchable combobox, and a calendar/date picker, plus a live /ui-components showcase page so you can see what exists before building a new one from scratch:

Every color and radius comes from light and dark tokens in src/app/styles/tokens.css, mapped to Tailwind utilities. The number isn't the point; the point is that composition and accessibility come for free because they're built on Radix, and because the components are just code in your repo, extending one (a new variant) doesn't mean waiting on an upstream release. Domain-specific UI (the auth forms, the dashboard shell) lives separately under src/components/auth/ and src/components/layout/, so the line between "generic primitive" and "feature-specific composition" stays visible in the folder structure itself.

10. Data fetching: don't turn everything into React state

Recommended practice: Server Components and TanStack Query solve different problems, and the 2026 consensus (backed by both the Next.js docs and the wider React ecosystem) is that they're complementary, not competing. Server Components are the right tool for the initial, server-known render, a dashboard's first paint, a product list. TanStack Query is the right tool for anything that needs client-side behavior after that: pagination, optimistic mutations, background refetching, stale-while-revalidate caching, infinite scroll. Reaching for useEffect plus manual useState for server data in 2026 means rebuilding caching, retries, and race-condition handling that TanStack Query already solved. The inverse mistake also happens: wrapping genuinely static, server-known data in a client-side query hook just adds a network waterfall and a loading spinner where a Server Component would have sent the HTML already rendered.

How Next-Elite handles it: QueryClientProvider is pre-configured in src/app/providers.tsx with sensible defaults (a 60-second staleTime, 5-minute gcTime, one retry, no refetch on window focus), ready to wire useQuery / useMutation against your REST, GraphQL, or BFF endpoints. It's deliberately not mandatory scaffolding around every fetch; server-renderable data still belongs in the Server Component that renders it.

11. Environment variables should fail safely

Recommended practice: a misconfigured environment variable should be a loud error, not a silent undefined that surfaces as a broken feature in production three weeks later. This means validating both server-only and public (NEXT_PUBLIC_*) variables against a schema, and being deliberate about which is which, since a secret accidentally marked public ships straight to the browser bundle.

How Next-Elite handles it: variables are validated by src/libs/env.ts via T3 Env, and that module is only imported by server code, so the validation library itself doesn't ship to the browser. A couple of specific decisions worth calling out because they're not the only valid choice: BETTER_AUTH_URL is optional and derives from VERCEL_URL in production rather than requiring manual configuration on every deploy, and a missing BETTER_AUTH_SECRET logs a warning instead of crashing the build, a deliberate softness so local development and CI don't grind to a halt over a secret you'll set before the real deploy. SKIP_ENV_VALIDATION=true exists specifically for CI and Docker build steps where secrets genuinely aren't available yet at build time.

12. SEO should be part of the architecture

Recommended practice: metadata, Open Graph tags, a sitemap, robots.txt, and a web manifest shouldn't be a checklist item the week before launch, scattered across whatever files happened to need them at the time. Centralizing them means updating your domain or title once, not hunting through six files hoping you didn't miss one.

How Next-Elite handles it: src/features/site/site.config.json is the single source of truth:

{
  "appName": "Next Elite",
  "domain": "https://yourdomain.com",
  "tagline": "Frontend-first, API-driven, batteries included.",
  "title": "Next Elite - Production-Ready SaaS Boilerplate",
  "description": "Frontend-first Next.js 16.4 + React 19 boilerplate with i18n, RBAC and BetterAuth."
}

The root layout's metadata and JSON-LD structured data, sitemap.ts, robots.ts, and manifest.ts all read from this one file (with NEXT_PUBLIC_APP_URL able to override the domain), along with the locale configuration, so localized routes and PWA metadata stay in sync with the rest of the i18n setup instead of drifting from it. There's also a /llms.txt file, a machine-readable summary for AI crawlers and assistants, which is a small 2026 addition that costs nothing and helps AI tools describe your product accurately.

13. Performance should be a default, not a final optimization

Recommended practice: the practical levers in 2026 are the same ones they've been for a few years, rendering on the server by default, minimizing the client JavaScript boundary, using next/image correctly (setting priority and sizes deliberately rather than accepting defaults everywhere), and measuring instead of guessing. What's changed is the tooling underneath: Turbopack graduated to stable as the default bundler in Next.js 16, and the 16.x line has continued shipping real, measured startup and rendering improvements release over release. None of that replaces measuring your specific app; bundle analysis and a Lighthouse run tell you where your app actually spends its budget, which is never quite the generic advice.

One tooling detail that catches people out: @next/bundle-analyzer only works with webpack, so under Turbopack it silently does nothing. Use Next's built-in Turbopack analyzer instead (npx next experimental-analyze).

How Next-Elite handles it: I ran exactly that analysis on Next-Elite and it found three things that were on every page without being needed there: the Sentry browser SDK (even when no DSN was set), Zod and the env validator (pulled into the browser through the auth provider and site config), and the ApexCharts library (loaded as soon as any chart rendered, even below the fold). The fixes were small and boring:

Sentry now loads lazily, and only when NEXT_PUBLIC_SENTRY_DSN is set, including inside the error boundaries.
Server-only values are passed to client components as props, and the site config is validated in tests instead of in the browser.
Charts load their library only when they scroll into view.
Only the font subset the app actually uses is loaded.

Together that cut first-load JavaScript by 21–24% per page (the home page went from 425 KB to 336 KB gzipped), and the live demo's total transfer roughly halved, from 906 KB to 462 KB.

The project's Lighthouse report shows 100 across Performance, Accessibility, Best Practices, and SEO, and 3/3 on Agentic Browsing:

That number describes the starting point; it's not a guarantee that survives you adding a heavy client-side library without thinking about it. That's exactly why the analyzer step belongs in your workflow, not just in a launch checklist.

14. Testing strategy

Recommended practice: unit and component tests catch logic bugs and rendering regressions fast, cheaply, and in isolation. End-to-end tests catch the thing unit tests structurally can't, whether the whole system actually works together, but they're slower and more expensive to maintain, which means writing them for the handful of flows that actually matter (login, the core happy path) rather than trying to E2E everything. Setting up this infrastructure after a project is already painful to test is a common regret; it's cheaper to have it from the first feature.

How Next-Elite handles it: Vitest and React Testing Library cover unit and component tests (config/vitest.config.ts), split into a fast node project for .test.ts logic and a jsdom project for .test.tsx components. Tests live in src/tests/, mirroring the src/ structure, with a renderWithProviders helper (@/tests/render) for components that need the app's context, i18n, theme, auth, React Query, so testing a component that reads the current locale doesn't mean hand-wiring four providers per test file. Playwright covers end-to-end, including the home page, the health endpoint, and the security headers, running on port 6767 against next dev locally (all browsers) and against a production next start build in CI (Chromium only, for speed). npm run check is the single CI gate: typecheck, lint, dead-code detection, and tests, in that order, so a broken type or an unused export fails the build before a flaky E2E test would even get a chance to run.

15. Code quality is an engineering system

Recommended practice: linting and formatting stop being cosmetic once a team grows past one person; they're what keeps "the way we do things" from depending on everyone remembering the rules. The honest 2026 state of the tooling landscape is a genuine trade-off, not a clean win for either side. Rust-based linters like Oxlint are dramatically faster than ESLint, independent 2026 benchmarks put the gap at roughly 50 to 100 times on large codebases, but ESLint still has by far the larger plugin ecosystem, meaning teams with heavy plugin dependencies (custom accessibility rules, framework-specific configs) often run both rather than fully switching. For a new project without that legacy plugin baggage, going Oxlint-first is a reasonable, increasingly common choice; for an existing large codebase with deep ESLint plugin investment, a hybrid or gradual migration is the more honest recommendation.

How Next-Elite handles it: Oxlint and Oxfmt handle linting and formatting, chosen specifically because the project has no legacy ESLint plugin dependency to migrate away from, it's a new codebase, so there was nothing to preserve by staying on the slower tool. Knip catches dead code and unused dependencies. Dependencies are pinned to exact versions (.npmrc sets save-exact=true) and kept current by Renovate and Dependabot, so an update is always a reviewed pull request, never a surprise in a fresh install. Lefthook wires all of it into git hooks: a pre-commit hook runs Oxlint and Oxfmt, a commit-msg hook enforces Conventional Commits via Commitlint, and a pre-push hook runs the full npm run check gate before code ever reaches a PR, which catches problems at the cheapest possible point, before CI, not after.

In 2026 there's a new member of the team the rules have to reach: AI coding agents. A linter can't tell an agent "use the existing card component instead of writing a new one." So Next-Elite ships its conventions in a form agents read: an AGENTS.md for tools like Cursor and Codex, and a project-standards skill for Claude Code. They tell the agent to reuse existing components first, add a variant instead of duplicating a component, use design tokens only, keep public pages as Server Components, and ask before making structural changes. That's the same "the way we do things" problem, extended to contributors that don't attend code review.

16. Observability from day one

Recommended practice: "it works on my machine" is not a monitoring strategy, and neither is waiting for a user to report a bug in a support ticket. Error tracking and a basic health endpoint cost almost nothing to set up and are the difference between finding a production issue in minutes versus discovering it days later from a support ticket. The 2026 addition: observability shouldn't cost every visitor bundle size. Load your error tracking SDK lazily so it never competes with the first paint.

How Next-Elite handles it: Sentry is wired for both client and server instrumentation (instrumentation.ts, instrumentation-client.ts), and both error boundaries report to it. The browser SDK loads lazily, and only when a DSN is configured, so projects that don't use Sentry ship none of it. Vercel Analytics is included for basic page analytics and renders only when the app is actually deployed on Vercel, so self-hosted deploys don't make a failing request on every page. A GET /api/health endpoint exists specifically so a load balancer, Dokploy, or your own uptime monitor has something concrete to poll. None of this replaces a real incident-response process for a team that needs one; it's the minimum that should exist before you need it, not a substitute for a mature observability stack at scale.

17. Docker and deployment should be boring

Recommended practice: deployment infrastructure shouldn't force an architectural rewrite six months in. Standalone output, multi-arch container builds, a real health check, and security headers set in code (not in some dashboard nobody remembers configuring) are what let you move a project from Vercel to a VPS, or from a single instance to several, without touching application code.

How Next-Elite handles it: the Dockerfile is a multi-stage build on a Google Distroless base image (gcr.io/distroless/nodejs22-debian12), so the runtime image contains no shell or package manager. It uses Next.js's standalone output with a built-in HEALTHCHECK against /api/health, and Buildx support means one command produces images for both linux/amd64 and linux/arm64, useful for self-hosting on ARM (Oracle Cloud's free tier, AWS Graviton, a Raspberry Pi). One detail that trips people up: NEXT_PUBLIC_* values are inlined into the JavaScript at build time, so they're passed as Docker build args, while server secrets like BETTER_AUTH_SECRET are read at runtime.

Security headers live in next.config.mjs: a strict Content Security Policy, HSTS, X-Frame-Options: DENY, nosniff, Referrer-Policy, and Permissions-Policy, with E2E tests checking that they're actually sent. One practical lesson from running the live demo behind Cloudflare: a strict CSP also blocks the scripts your host injects (Cloudflare Web Analytics, in my case), so allow-list them deliberately instead of loosening the whole policy.

It deploys to Vercel with one click, or to Dokploy as a self-hosted alternative, using the same Dockerfile and health check either way. The point isn't a preference for one platform, it's that the same container-based deployment story works whether you're on a $0 Vercel hobby plan or your own hardware.

18. What I intentionally did NOT include

A good boilerplate is defined as much by what it refuses to bundle as by what it ships. Next-Elite intentionally does not include:

A database or ORM. No Prisma, no Drizzle, no Postgres. This is the direct consequence of the API-driven architecture decision in section 3, not an oversight.
Payments or billing. Stripe, subscriptions, and usage metering are product-specific decisions that vary too much between projects to standardize in a starter.
Queues or Redis. Background jobs and caching infrastructure depend entirely on what your backend already provides.
A specific backend framework. Next-Elite doesn't assume Go, Node, or Laravel behind it, because assuming any one of them would break the "drop it on any backend" promise.
Multi-tenant or hierarchical permission graphs. The RBAC system covers two roles well; it doesn't try to be a general-purpose authorization engine.
A wired-up password reset email flow. The reset page and form are there, but sending the email is your backend's job, so the form is ready to connect rather than tied to one email provider.

Every one of these is a real feature other boilerplates in the ecosystem provide well, some of them, like ixartz's Next.js Boilerplate, ship a database, multi-tenancy, and a full auth/roles system out of the box, and paid options like ShipFast or MakerKit bundle Stripe, transactional email, and enterprise compliance features for a one-time fee. Building that same foundation from scratch has been estimated at somewhere in the $7,500 to $12,000 range in developer time, which is exactly why those paid options exist and are worth it for the right project. If you want any of what's on this list bundled in, one of those is very likely the better starting point than Next-Elite. That's not a hedge, it's the honest answer to "why doesn't this have X."

19. The trade-offs

None of this architecture is universally correct, and presenting it that way would be dishonest.

Next-Elite is probably overkill for:

Single-page landing sites
Tiny prototypes and weekend experiments
Projects where Next.js is genuinely the entire backend and will stay that way

It's a stronger fit for:

SaaS applications with more than one user role
Admin panels, ERPs, dashboards, and internal tools
Multilingual products, especially ones that need RTL support
Products backed by an existing REST, GraphQL, or BFF API
Teams (or solo developers) who've noticed they're rebuilding the same auth-and-RBAC foundation across projects

If you're not sure which camp you're in: if you can describe your project without the words "roles," "dashboard," or "multiple languages," you probably don't need this, and that's a legitimate outcome, not a failure to be convinced.

20. The actual boilerplate: Next Elite

I built Next Elite because I kept answering the same architectural questions from scratch on every new SaaS project, and I wanted the answer to compound instead of resetting. It's MIT-licensed and free to use as a template.

What you get, in one pass:

Next.js 16.4 (App Router, Turbopack, Server Actions) + React 19.3 + TypeScript 7
Feature-based architecture under src/features/
BetterAuth (email/password + Google OAuth) with permission-based RBAC, split-pane auth UI, server-side guards, parallel-route dashboard slots
next-intl across 6 languages including RTL, cookie-based, type-checked translation keys
50+ shadcn/ui primitives and custom components on Tailwind CSS v4 and Radix UI, with light/dark design tokens
TanStack Query pre-configured for your REST/GraphQL/BFF API
Sentry (lazy-loaded) + Vercel Analytics + a /api/health endpoint
Security headers (CSP, HSTS, frame and content-type protection) set in code
Vitest + React Testing Library + Playwright
Oxlint + Oxfmt + Knip + Lefthook + Commitlint, with pinned dependencies kept current by Renovate and Dependabot
AGENTS.md and a project-standards skill so AI coding agents follow the project's conventions
Standalone Distroless Docker build, multi-arch (amd64/arm64), Dokploy-ready, one-click Vercel deploy
SEO metadata, JSON-LD, dynamic sitemap, robots.txt, PWA manifest, and llms.txt from one config file
All demo code in one folder, removable with npm run demo:remove

Who should use it: teams and solo developers building a role-based SaaS, admin panel, or dashboard product against an existing or planned API, especially if multi-language support is on the roadmap.

Who shouldn't: anyone who needs a bundled database on day one, or whose project is small enough that this is genuinely more structure than the problem needs. Use create-next-app for that, or the official Next.js SaaS Starter if you want the framework team's own opinionated take.

Quick start

git clone https://github.com/salmanshahriar/Next-Elite.git
cd Next-Elite
npm install
cp .env.example .env
npm run dev

Open http://localhost:6767. You'll land on a working app with auth, RBAC-gated dashboards, six languages, and the rest of this list already wired together, not a scaffold you still have to assemble. When you're ready to build your own product, run npm run demo:remove and npm run check.

Live Demo · GitHub Repo · Use This Template · Deploy on Vercel

21. Final checklist: my 2026 Next.js project checklist

Whether or not you use Next-Elite, this is the list I'd check before calling a Next.js project production-ready:

Architecture

✅ Code is grouped by feature, with genuinely shared UI kept in one place
✅ Decided on purpose whether Next.js owns the database or consumes an API
✅ Demo or example code is isolated and removable

Rendering & data

✅ Pages and layouts are Server Components; 'use client' only at small leaf boundaries
✅ Server-only values are passed to client components as props, not imported
✅ Server-known data renders on the server; client data uses TanStack Query, not useEffect + useState

Security

✅ Authorization runs in Server Components, Route Handlers, and Server Actions, never only in middleware
✅ Roles and permissions are defined in one typed place and checked through a few helpers
✅ Auth has a real database adapter before multi-instance production
✅ Security headers (CSP, HSTS, frame protection) are set in code and tested

Type safety & config

✅ Environment variables are validated, with server and public variables clearly separated
✅ Translation keys, permissions, and config are typed, not just component props

i18n & UI

✅ Every user-facing string goes through i18n, and every locale has the same keys
✅ Layouts use logical start/end spacing so RTL works
✅ Colors and radii come from design tokens, with light and dark values
✅ Every data view has loading, empty, and error states

SEO & performance

✅ Metadata, sitemap, robots, manifest, and JSON-LD come from one config
✅ Bundle analyzed with the Turbopack analyzer; heavy libraries load lazily
✅ Lighthouse checked on the production build

Quality & delivery

✅ One check command runs typecheck, lint, dead-code detection, and tests
✅ Git hooks run the cheap checks before code leaves the machine
✅ Dependencies are pinned and updated through reviewed pull requests
✅ Unit/component tests plus E2E for the flows that matter
✅ AI coding agents get the project's conventions in AGENTS.md (or a skill)
✅ Error tracking, a health endpoint, and a container build with a health check exist before launch

I built an opensource production-ready NEXT.JS STARTER KIT!

Salman Shahriar — Wed, 19 Nov 2025 19:11:28 +0000

Every time I started a new Next.js project, I lost the first week to setup.

Authentication. Internationalization. Role-based access. SEO meta tags. Environment validation. Error monitoring. Linting. Testing. CI pipelines.

By the time I had a working foundation, the excitement was gone, buried under configuration files and boilerplate glue code.

I kept rebuilding the same foundation across SaaS projects, so I stopped and built it once: Next Elite.

It is a frontend-first Next.js 16.4 + React 19.3 boilerplate designed to consume APIs (REST/GraphQL/BFF) instead of owning a database, so you can drop it on top of any backend you already have. It is feature-based, optimized for speed, SEO, and developer productivity, and includes 50+ custom and reusable UI components built on shadcn/ui, plus pre-built split-pane auth layouts and role-based dashboard layouts. It is 100% open source under the MIT license.

Live Demo · GitHub Repo · Use This Template · Deploy on Vercel

TL;DR: git clone, npm install, cp .env.example .env, npm run dev. Open http://localhost:6767. You get auth, RBAC dashboards, 6-language i18n, 50+ UI components, SEO, forms, testing, CI, and AI-agent-ready coding rules. Try the demo.

Why Another Next.js Boilerplate? (The Concept)
What's Inside: The Next Elite Stack & Features
Lighthouse Score: 100% Performance & SEO
Quick Start: Launch Your Project in 60 Seconds
Deep Dive: How Next Elite Works Under the Hood
Clean Feature-Based Directory Structure
Configuration & Environment Variables
Development, Testing & CI/CD
Architectural Caveats: What Next Elite is NOT
Production Checklist: Going Live
Contributing & Open Source

1. Why Another Next.js Boilerplate? (The Concept)

Most Next.js starters on GitHub are either too bare (a dark mode toggle and a "TODO: add auth" comment) or too bloated (Prisma, PostgreSQL, Docker Compose, Stripe webhooks, and an ORM tightly coupled to their own DB schema).

If you already have a backend (written in Go, Python, Laravel, or Node.js) or want a backend-for-frontend (BFF) architecture, tearing the built-in database layer out of a boilerplate is painful.

Next Elite sits in the sweet spot. It handles the complex frontend foundation, UI components, role management, and locale settings while leaving the database and API layer up to you. It's built to consume APIs directly, so you can drop it on top of any backend you already have.

When to use Next Elite

Next Elite is best for:

SaaS apps with multiple user roles.
Admin panels, ERPs, and dashboards.
Multi-lingual/Internationalized products (LTR + RTL).
Frontends consuming an existing backend or BFF.
Projects requiring a clean, feature-based modular structure.

It is probably overkill for:

Single-page landing sites.
Apps that need a tightly-coupled DB layer (API-only design).

2. What's Inside: The Next Elite Stack & Features

Here is the tech stack built into Next Elite, broken down by category:

Frameworks & Core

Next.js 16.4 (App Router) - Fast, modern React framework with Turbopack, standalone output for Docker/self-hosting, and full support for React 19.3 features (Server/Client components, Server Actions).
TypeScript 7 - End-to-end type safety for rock-solid refactoring and developer experience.
Node.js 22.12+ - Built on the Node.js 22 LTS runtime.
Feature-Based Architecture - Structured around self-contained vertical slices/feature folders under src/features/ for maximum modularity and clean separation of concerns.

Authentication & Access Control

BetterAuth - Out-of-the-box email/password and Google OAuth authentication using /api/auth/* route handlers. Configure admin emails via the comma-separated AUTH_ADMIN_EMAILS server variable.
Auth UI & Layout - Split-pane login, register, and password reset pages with a custom WebGL particle background animation, and a topbar with theme toggle and language switcher. Login and register are wired to BetterAuth; the password reset form is UI-only, ready to connect to your backend's reset flow.

Role-Based Access Control (RBAC) - Flexible RBAC (user and admin roles) with server-side guards (requireUser, requirePermission) and parallel route slots (@admin, @user) for role-agnostic routing.
Dashboard & Navigation - Modern sidebar navigation with fixed bottom Settings (/settings) and Logout (with a confirm dialog) actions, collapsible state remembered in a cookie, mobile sheet, and topbar breadcrumbs generated from the URL. Users without permission land on a dedicated /unauthorized page.

Internationalization (i18n)

next-intl - Type-safe, cookie-based localizations (no URL prefix) with support for English, বাংলা, العربية (RTL), Français, Español, and 简体中文. Translation keys are type-checked (t("key") works; typos fail at compile time), and the language switcher updates the locale through a Server Action.

UI & Styling

Tailwind CSS 4 - Utility-first styling with @tailwindcss/postcss and tw-animate-css.
Design Tokens - Light and dark color, radius, and spacing tokens in src/app/styles/tokens.css, mapped to Tailwind utilities, so there are no hard-coded colors anywhere.
shadcn/ui - 50+ highly customizable UI components built with Tailwind CSS, Radix UI, and CVA variants: cards, stat cards, charts, a sortable and paginated data table, forms, selects, comboboxes, a calendar/date picker, dialogs, sheets, and more. Includes a live /ui-components showcase page.

Theme Support - Light, dark, and system themes, with a circular "wave" transition (View Transitions API) when you toggle, and no flash on load because the theme is read on the server.
Feedback Built In - Toast notifications with Sonner, a top page-loading bar, skeleton loading states, and loading-aware buttons.

API & Data Fetching

TanStack Query (React Query) - Pre-configured QueryClientProvider in src/app/providers.tsx with sensible defaults (staleTime, gcTime, retry). Ready to wire useQuery / useMutation hooks to your REST, GraphQL, or BFF endpoints.
Next Elite Server (Coming Soon) - A companion backend template built with NestJS, BetterAuth, Drizzle ORM, PostgreSQL, and multi-tenancy.

Observability & Infrastructure

Sentry Integration - Error tracking and performance instrumentation for client and server. The browser SDK loads lazily and only when NEXT_PUBLIC_SENTRY_DSN is set, so it never blocks the first page load.
Vercel Analytics - Page analytics via @vercel/analytics, rendered only when deployed on Vercel.
Health Probes - Direct GET /api/health endpoint for load balancers.
Security Headers - A strict Content Security Policy, HSTS, X-Frame-Options: DENY, nosniff, Referrer-Policy, and Permissions-Policy are set in next.config.mjs, and E2E tests check them.

Quality Gates & Tooling

Validated Config - Environment variables are validated on the server with T3 Env (src/libs/env.ts), and site.config.json is checked against its schema in unit tests, so neither ships zod to the browser.
Testing Suite - Unit/component testing with Vitest and React Testing Library (separate node and jsdom projects), and E2E testing with Playwright.
Pinned Dependencies - Exact versions only (.npmrc sets save-exact=true), kept up to date by Renovate and Dependabot.
Hygiene & Linting - Oxlint and Oxfmt for fast linting and formatting, plus Knip for dead code/dependency hygiene.
Git Hook Automation - Lefthook pre-commit hooks (oxlint + oxfmt), Commitlint for conventional commits, and a pre-push hook that runs npm run check.

AI Agent Ready

AGENTS.md + project-standards skill - The repo ships coding rules for AI agents (Claude Code, Cursor, Codex, and others). They require agents to reuse the existing components first, add variants instead of duplicating components, use design tokens only, render public pages on the server, and ask before making structural changes. That way, AI-written code still looks like the rest of the codebase.
/llms.txt - A machine-readable project summary for AI crawlers and assistants.

3. Lighthouse Score: 100% Performance & SEO

One of the key goals of Next Elite was flawless performance and SEO defaults. Out of the box, the production build scores a perfect 100 for Performance, Accessibility, Best Practices, and SEO on Lighthouse, and passes all 3/3 Agentic Browsing checks:

This comes from rendering Server Components by default, serving SEO meta tags from a single configuration file, and keeping client-side JavaScript lean:

Heavy libraries like ApexCharts load only when a chart scrolls into view.
Sentry loads lazily and only when it is configured.
Validation libraries stay on the server.
Only the font subsets the app needs are loaded.

4. Quick Start: Launch Your Project in 60 Seconds

One-click Deploy

Deploy this template to Vercel with one click:

Deploy with Vercel

Set the environment variables from .env.example in your Vercel project (Production + Preview).

Prerequisites

Node.js 22.12 or later
npm

Local Setup

Clone the repository and navigate into it:

   git clone https://github.com/salmanshahriar/Next-Elite.git
   cd Next-Elite

Install dependencies:

   npm install

Set up your environment variables:

   cp .env.example .env

Start the development server:

   npm run dev

Open http://localhost:6767 to view your local instance.

Demo Credentials

When NEXT_PUBLIC_DEMO_MODE=true is enabled, the login screen includes a quick-fill panel with these seed credentials:

Role	Email	Password
User	`user@test.com`	`12345678`
Admin	`admin@test.com`	`12345678`

Removing the Demo Code

All demo code (landing page, /ui-components showcase, promo logos, demo accounts) lives in src/_demo(DELETE)/. When you're ready to build your own app, run:

npm run demo:remove
npm run check

The script deletes the demo folder and rewrites every file that references it, so you're left with a clean, working app. CI runs this same removal on every push to make sure it keeps working.

Docker Setup

The production image uses a multi-stage Google Distroless base image (gcr.io/distroless/nodejs22-debian12) for maximum security, zero unnecessary OS packages, and a minimal image size.

Run the application locally via Docker:

cp .env.example .env
docker build -t next-elite .
docker run --rm --env-file .env -p 6767:6767 next-elite

Or using Docker Compose:

docker compose up --build

The Dockerfile uses Next.js standalone output with a built-in health check against /api/health.

Note: NEXT_PUBLIC_* variables are inlined into the JavaScript at build time, so pass them as build args (--build-arg NEXT_PUBLIC_APP_URL=..., NEXT_PUBLIC_GOOGLE_AUTH_ENABLED, NEXT_PUBLIC_DEMO_MODE). Server-only secrets like BETTER_AUTH_SECRET are read at runtime from --env-file.

Multi-Arch Deploy (ARM64 + AMD64)

The Dockerfile produces images that run on both linux/amd64 and linux/arm64. Build a multi-arch image with Buildx:

docker buildx create --name multiarch --use   # one-time setup
docker buildx build --platform linux/amd64,linux/arm64 -t next-elite .

This is ideal for self-hosting on ARM servers (Oracle Cloud, Raspberry Pi, AWS Graviton, etc.).

Dokploy Deployment

This template is ready for Dokploy - the open-source PaaS.

Create a new Application in Dokploy and point it to your fork of this repo.
Set the build type to Dockerfile (auto-detected).
Configure environment variables via the Dokploy UI (see .env.example).
Deploy - Dokploy automatically builds and runs the container with health checks.

The included HEALTHCHECK instruction pings /api/health so Dokploy can monitor and restart the container if it becomes unresponsive.

View Available Scripts & CLI Commands

Command	Description
`npm run dev`	Start the dev server (port 6767)
`npm run build`	Production build
`npm run start`	Start the production server (port 6767)
`npm run start:standalone`	Run standalone server (Playwright CI)
`npm run typecheck`	`tsc --noEmit`
`npm run lint`	Oxlint + Oxfmt check
`npm run lint:fix`	Auto-fix with Oxlint + Oxfmt
`npm run format`	Format with Oxfmt
`npm run format:check`	Check formatting with Oxfmt
`npm run knip`	Detect unused files / exports / deps
`npm run check`	CI gate: typecheck + lint + knip + tests
`npm run test`	Vitest run
`npm run test:watch`	Vitest watch mode
`npm run demo:remove`	Delete all demo code
`npm run playwright:install`	Download Playwright browsers
`npm run playwright:install:deps`	Install OS libs for browsers (Linux)
`npm run e2e`	Playwright E2E
`npm run e2e:ui`	Playwright UI mode
`npm run e2e:webkit`	Playwright WebKit only

5. Deep Dive: How Next Elite Works Under the Hood

The big picture: a page is rendered on the server, auth/role is checked there, and any live data is fetched on the client.

flowchart TB
    User([User]) --> Page

    subgraph Server["Server (runs first)"]
        Page[Page / Layout]
        Guard["requireUser() / requirePermission()"]
        Page --> Guard
        Guard -->|reads session + role| Auth[BetterAuth]
    end

    subgraph Client["Client (runs in browser)"]
        Hook["useQuery (TanStack Query)"]
        Hook -->|fetch| Api["Your backend API"]
    end

    Page -->|sends HTML| User
    Page -.->|interactive parts| Hook

How a request flows:

User opens a page - the Server Component renders first.
Auth + role check - requireUser() / requirePermission() read the BetterAuth session and redirect to /login or /unauthorized if needed.
HTML is sent to the browser; translations come from messages/ via next-intl.
Live data (lists, forms, etc.) is fetched on the client with TanStack Query → your API (REST/GraphQL/BFF).

Type-Safe RBAC & BetterAuth

Permissions are checked on the server, not with scattered if (role === 'admin') checks.

View Auth & RBAC Usage

// Server Component example
import { requirePermission } from '@/features/auth/rbac/require';
import { getTranslations } from 'next-intl/server';

const AdminDashboardPage = async () =&gt; {
  const [, t] = await Promise.all([
    requirePermission('dashboard.view:admin'),
    getTranslations('dashboard.admin'),
  ]);
  return <h1>{t('title')}</h1>;
};

export default AdminDashboardPage;

Next Elite uses Next.js Parallel Routes to keep layouts role-agnostic. The routing structure mounts specific slots based on the user's role, and both roles share the same URLs (/dashboard, /analytics, /profile, /settings):

src/app/(protected)/
  ├── @admin/               # Admin slots (dashboard, analytics, profile, settings)
  ├── @user/                # User slots (dashboard, analytics, profile, settings)
  └── layout.tsx            # Picks slot based on permissions

Adding a Role

Append the role to the UserRole union in src/features/auth/rbac/permissions.ts.
Map permissions for the role in ROLE_PERMISSIONS in the same file.
Optional: add a parallel route slot - src/app/(protected)/@/... - and update (protected)/layout.tsx to render it based on permissions.

Zero-Prefix cookie-based i18n

Unlike standard i18n setups that force prefixes like /en/ or /es/ into the URL (which clutters routes and duplicates routing config), Next Elite stores the locale in a NEXT_LOCALE cookie, so URLs have no prefix.

Adding a Language

Add the locale code to languages.supported in site.config.json and add an entry under languages.locales.
Create messages/.json mirroring messages/en.json.
The next-intl runtime picks it up automatically; types update from src/global.d.ts.

Site & SEO Configuration

src/features/site/site.config.json is the single source of truth for SEO metadata, dynamic sitemaps, localized routes, and the PWA manifest:

{
  "appName": "Next Elite",
  "domain": "https://yourdomain.com",
  "tagline": "Frontend-first, API-driven, batteries included.",
  "title": "Next Elite - Production-Ready SaaS Boilerplate",
  "description": "Frontend-first Next.js 16.4 + React 19 boilerplate with i18n, RBAC and BetterAuth."
}

The file is validated against a Zod schema in the unit tests, so a typo fails npm run check instead of breaking production.

View Forms Usage (React Hook Form + Zod)

'use client';

import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import { loginSchema, type LoginInput } from '@/features/auth/schemas/login';

const form = useForm({
  resolver: zodResolver(loginSchema),
  defaultValues: { email: '', password: '' },
});

6. Clean Feature-Based Directory Structure

Next Elite uses a Feature-Based (Vertical Slice) Architecture under src/features/. Each folder contains its own hooks, schemas, server helpers, and config. Shared UI and layout pieces live under src/components/, and cross-cutting infra lives under src/libs/.

View Directory Structure

.
├── .github/
│   ├── workflows/            CI: check.yml (incl. demo removal) + playwright.yml
│   ├── dependabot.yml        Dependency updates
│   └── renovate.json         Dependency updates
├── .claude/skills/           project-standards skill for AI coding agents
├── config/                   Vitest, Playwright, and Knip configs
├── e2e/                      Playwright specs
├── messages/                 next-intl translations (en, bn, ar, fr, es, zh)
├── public/                   Static assets + llms.txt
├── scripts/                  remove-demo.mjs (npm run demo:remove)
├── .vscode/                  Oxc extension + format-on-save settings
├── components.json           shadcn/ui CLI config
├── .env.example              Environment variable template
├── .npmrc                    save-exact=true (pinned dependencies)
├── .oxlintrc.json            Oxlint rules (Next.js, TypeScript, React, Unicorn)
├── .oxfmtrc.json             Oxfmt formatter config (Tailwind class sorting)
├── Dockerfile                Multi-stage Distroless build + HEALTHCHECK
├── docker-compose.yml
├── next.config.mjs           Security headers, Sentry, next-intl, standalone output
├── postcss.config.mjs        Tailwind CSS v4
├── package.json              scripts + Commitlint config
├── package-lock.json
├── tsconfig.json
├── lefthook.yml              Git hooks (pre-commit, commit-msg, pre-push)
├── AGENTS.md                 Rules for AI coding agents
├── src/
│   ├── _demo(DELETE)/        Landing page, showcase, demo accounts (delete for your app)
│   ├── app/                  App Router
│   │   ├── (auth)/           Login, register, &amp; reset-password pages
│   │   ├── (public)/         Public pages
│   │   ├── (protected)/      Authenticated area + RBAC
│   │   │   ├── @admin/       Admin slots (dashboard, analytics, profile, settings)
│   │   │   ├── @user/        User slots (dashboard, analytics, profile, settings)
│   │   │   ├── unauthorized/ Shown when a role lacks permission
│   │   │   └── layout.tsx    Picks slot based on permissions
│   │   ├── api/              Route handlers (BetterAuth, health)
│   │   ├── styles/           tokens.css, base.css, components.css (theme transition)
│   │   ├── error.tsx         Error boundary (reports to Sentry)
│   │   ├── global-error.tsx  Root error boundary
│   │   ├── not-found.tsx     404 page
│   │   ├── fonts.ts          Inter typography configuration
│   │   ├── layout.tsx        Root layout, SEO, fonts, providers
│   │   ├── providers.tsx     Theme + Auth + TanStack Query
│   │   ├── manifest.ts       Web app manifest
│   │   ├── robots.ts         robots.txt
│   │   └── sitemap.ts        Dynamic sitemap
│   ├── components/
│   │   ├── auth/             Auth forms &amp; particle animation canvas
│   │   ├── icons/            Centralized SVG icon components &amp; barrel export
│   │   ├── layout/           App shell, navigation sidebars, topbar &amp; branding
│   │   ├── shared/           Page header, theme &amp; language controls, user dropdown
│   │   └── ui/               shadcn/ui primitives &amp; custom components
│   ├── features/             Feature modules (vertical slices)
│   │   ├── auth/             BetterAuth + RBAC (hooks, lib, rbac, schemas, server)
│   │   ├── i18n/             next-intl config (routing, request, actions)
│   │   └── site/             site config, schema, base URL + locale utilities
│   ├── hooks/                Shared React hooks
│   ├── libs/                 Cross-cutting infra (env, query-client, utils)
│   ├── tests/                Unit/component tests (components, features, libs) + renderWithProviders
│   ├── instrumentation.ts    Server Sentry init
│   ├── instrumentation-client.ts  Client Sentry init (lazy)
│   └── global.d.ts           next-intl type augmentation
└── ...

7. Configuration & Environment Variables

Environment variables are validated on the server by src/libs/env.ts (T3 Env).

BETTER_AUTH_URL is optional - derived from VERCEL_URL in production, http://localhost:6767 locally.
BETTER_AUTH_SECRET (32+ chars) must be set at runtime in production. A missing secret logs a warning instead of crashing the build.
Set SKIP_ENV_VALIDATION=true in CI / Docker build steps when env vars aren't available yet.

Key variables:

Variable	Purpose
`BETTER_AUTH_SECRET`	Auth signing secret (32+ chars)
`GOOGLE_CLIENT_ID/SECRET`	Optional Google OAuth
`NEXT_PUBLIC_GOOGLE_AUTH_ENABLED`	Show Google sign-in button
`AUTH_ADMIN_EMAILS`	Comma-separated admin role emails
`NEXT_PUBLIC_DEMO_MODE`	Demo credentials panel (disable for prod)
`SENTRY_DSN` / `NEXT_PUBLIC_SENTRY_DSN`	Optional Sentry error tracking
`NEXT_PUBLIC_APP_URL`	Public app URL (SEO/OAuth)

8. Development, Testing & CI/CD

Editor Setup

Install the Oxc VS Code extension (oxc.oxc-vscode) for format-on-save and Oxlint fix-on-save. Project settings in .vscode/settings.json are preconfigured.

Testing

Unit / component: Vitest + React Testing Library (config/vitest.config.ts). Tests live in src/tests/, mirroring the src/ folder structure. Use renderWithProviders from @/tests/render for components that need app context (i18n, theme, auth, React Query). Plain render is fine for isolated UI primitives.
End-to-end: Playwright in e2e/ checks the home page, the health endpoint, and the security headers. It runs on port 6767 (127.0.0.1). Local runs use next dev (all browsers); CI uses production next start (Chromium only). Run playwright:install before the first E2E run; on Linux, WebKit needs playwright:install:deps (sudo). Stop npm run dev before npm run e2e - E2E starts its own server.

CI/CD Pipeline

.github/workflows/check.yml - typecheck → lint → knip → unit tests → build on every push and PR, plus a job that runs npm run demo:remove on a clean copy and checks that the app still passes.
.github/workflows/playwright.yml - build → Playwright E2E (Chromium, production server).
.github/renovate.json - weekly grouped updates, automerging patch and minor versions while keeping majors separate.
.github/dependabot.yml - weekly grouped npm and GitHub Actions updates.

9. Architectural Caveats: What Next Elite is NOT

To keep the boilerplate clean and adaptable, I made specific design trade-offs:

No Database Bundled: There is no Prisma, Drizzle, Postgres, or MongoDB setup. Next Elite is built to communicate with an external API. Without a database configured, BetterAuth falls back to its built-in in-memory store, which is perfect for the demo and local development.
Simple RBAC System: The starter RBAC covers two roles (user and admin) with a fast-path admin list via environment variables. For complex multi-tenant permissions, map roles in your main database and API layer.
Cookie-Based i18n: Storing the locale in a cookie rather than a path prefix (like /en/dashboard) keeps routes simpler, but public pages render per request, and per-locale SEO indexing would need a custom path-prefixed router setup.
In-Memory Auth Store: Because of that fallback, users and sessions live in server memory by default. They're lost on restart and aren't shared between server instances, so production needs a database adapter (or point auth at your own backend).

10. Production Checklist: Going Live

Before deploying Next Elite to production, run through these essential steps:

Configure Auth Secrets: Set BETTER_AUTH_SECRET (at least 32 characters long) in your hosting dashboard.
Add a Database Adapter: Connect BetterAuth to a database (for example Postgres via Drizzle or Prisma) so users and sessions survive restarts and work across multiple instances. Optionally add Redis as secondary storage for sessions.
Remove the Demo: Run npm run demo:remove, or at least set NEXT_PUBLIC_DEMO_MODE=false.
Link Your API: Point NEXT_PUBLIC_APP_URL at your live domain and wire TanStack Query hooks to your REST/GraphQL/BFF service.
Update SEO Metadata: Update src/features/site/site.config.json with your project domain, OG image, and app description, and replace the images in public/.
Wire Password Reset: Connect the password reset form to your backend's reset email flow.
Enable Error Tracking: Set SENTRY_DSN and NEXT_PUBLIC_SENTRY_DSN to activate Sentry instrumentation.
Set SKIP_ENV_VALIDATION=true in CI/Docker build steps when env vars aren't available at build time.

11. Contributing & Open Source

Next Elite is free and open-source under the MIT license. Contributions, bug reports, and discussions are welcome!

Fork & branch from main (feat/..., fix/..., docs/...).
Ensure npm run check passes locally.
Use Conventional Commits.
Open a pull request.

If this boilerplate saved you time, a star helps more devs discover it

Live Demo · GitHub Repo · Use Template · Deploy on Vercel

DEV Community: Salman Shahriar

Next.js Best Practices in 2026: Why I Built Next-Elite

Table of Contents

1. What "best" should mean for a 2026 boilerplate

2. The 2026 landscape, honestly

3. Where the gap is

4. Why Next-Elite fills it

5. Feature walkthrough

6. Where Next-Elite is not the answer

7. Why now, specifically

8. Get started

Next.js Best Practices in 2026: The Boilerplate I Built So I Stop Repeating Myself

Table of Contents

1. What "production-ready" actually means in 2026

2. Start with architecture, not components

3. Frontend-first and API-driven architecture

4. Server Components vs Client Components

5. Authentication is not authorization

6. RBAC without scattering permission logic everywhere

7. TypeScript should enforce architecture, not just describe it

8. Type-safe internationalization

9. UI architecture with Tailwind + shadcn/ui

10. Data fetching: don't turn everything into React state

11. Environment variables should fail safely

12. SEO should be part of the architecture

13. Performance should be a default, not a final optimization

14. Testing strategy

15. Code quality is an engineering system

16. Observability from day one

17. Docker and deployment should be boring

18. What I intentionally did NOT include

19. The trade-offs

20. The actual boilerplate: Next Elite

Quick start

21. Final checklist: my 2026 Next.js project checklist

I built an opensource production-ready NEXT.JS STARTER KIT!

Table of Contents

1. Why Another Next.js Boilerplate? (The Concept)

When to use Next Elite

2. What's Inside: The Next Elite Stack & Features

Frameworks & Core

Authentication & Access Control

Internationalization (i18n)

UI & Styling

API & Data Fetching

Observability & Infrastructure

Quality Gates & Tooling

AI Agent Ready

3. Lighthouse Score: 100% Performance & SEO

4. Quick Start: Launch Your Project in 60 Seconds

One-click Deploy

Prerequisites

Local Setup

Demo Credentials

Removing the Demo Code

Docker Setup

Multi-Arch Deploy (ARM64 + AMD64)

Dokploy Deployment

5. Deep Dive: How Next Elite Works Under the Hood

Type-Safe RBAC & BetterAuth

Zero-Prefix cookie-based i18n

Site & SEO Configuration

6. Clean Feature-Based Directory Structure

7. Configuration & Environment Variables

8. Development, Testing & CI/CD

Editor Setup

Testing

CI/CD Pipeline

9. Architectural Caveats: What Next Elite is NOT

10. Production Checklist: Going Live

11. Contributing & Open Source

If this boilerplate saved you time, a star helps more devs discover it