DEV Community

Cover image for I built a production ready NEXT.JS starter so you dont have to!
Salman Shahriar
Salman Shahriar

Posted on

I built a production ready NEXT.JS starter so you dont have to!

#nextjs #react #boilerplate #betterauth

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 + React 19 boilerplate designed to consume APIs (REST/GraphQL/BFF) instead of owning a database, allowing you to drop it on top of any backend you already have. It is optimized for speed, SEO, and developer productivity, and it is 100% open source under the MIT license.

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

Next.js Elite production-ready SaaS boilerplate cover

TL;DR: git clone, npm install, cp .env.example .env, npm run dev. You get auth, RBAC dashboards, 6-language i18n, SEO, forms, testing, and CI. Try the demo.

Table of Contents

  1. Why Another Next.js Boilerplate? (The Concept)
  2. What's Inside: The Next Elite Stack & Features
  3. Lighthouse Score: 100% Performance & SEO
  4. Quick Start: Launch Your Project in 60 Seconds
  5. Deep Dive: How Next Elite Works Under the Hood
  6. Clean Feature-Based Directory Structure
  7. Architectural Caveats: What Next Elite is NOT
  8. Production Checklist: Going Live
  9. Contributing & Open Source

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

Most Next.js starters on GitHub are either too bare (providing just a dark mode toggle and a "TODO: add auth" comment) or too bloated (bundling 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 to build a backend-for-frontend (BFF) architecture, tearing out the built-in database layer from 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 fetching structure flexible. It’s built to consume APIs directly, allowing you to drop it on top of any backend you already have.

Who is this boilerplate for?

  • ✅ SaaS applications requiring complex role authorization.
  • ✅ Internationalized projects that need to support multiple languages (LTR and RTL).
  • ✅ Frontend-first architectures consuming REST, GraphQL, or a backend-for-frontend (BFF).
  • ❌ Single-page landing websites (Next Elite is likely overkill).
  • ❌ Tightly-coupled monoliths requiring a database layer in the same repository.

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

Here is the clean, high-performance tech stack built into Next Elite, broken down by core categories:

Frameworks & Core

  • Next.js 16 (App Router) & React 19 – Fast, modern React framework with full support for React 19 features (Server/Client components, Server Actions).
  • TypeScript 6 – End-to-end type safety for rock-solid refactoring and developer experience.
  • Node.js 22 (LTS) – Built on the latest 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 OAuth (Google) authentication using /api/auth/* route handlers. Configure admin emails via AUTH_ADMIN_EMAILS or NEXT_PUBLIC_AUTH_ADMIN_EMAILS.
  • 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.

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 compile-time).

UI & Styling

  • shadcn/ui – Highly customizable UI components built with Tailwind CSS, Radix UI, and CVA.

    Next Elite UI Components

  • Theme Support – Clean light/dark mode transitions via theme toggle.

API & Data Fetching

  • TanStack Query (React Query) – Powerful client-side state management, caching, and data synchronization.
  • apiFetch Client – A custom Zod-validated ofetch wrapper in src/libs/api-client.ts supporting type-safe queries and mutations. Includes a complete users example feature.

Observability & Infrastructure

  • Sentry Integration – Complete error tracking and performance instrumentation for client and server.
  • Logging – Clean, fast server-side logging using pino.
  • Rate Limiting – Optional rate-limiting helper using Upstash Redis.
  • Health Probes – Direct GET /api/health endpoint for load balancers.

Quality Gates & Tooling

  • Testing Suite – Unit/component testing with Vitest and React Testing Library, and E2E testing with Playwright.
  • Hygiene & Linting – ESLint 9, Prettier formatting, and Knip for dead code/dependency hygiene.
  • Git Hook Automation – Lefthook pre-commit hooks and Commitlint to maintain codebase quality.

3. Lighthouse Score: 100% Performance & SEO

One of the key goals of Next Elite was achieving flawless performance and SEO defaults. Out-of-the-box, the production build scores a perfect 100 across the board on Lighthouse:

Next Elite Lighthouse Report - 100 Performance, Accessibility, Best Practices, and SEO

This is achieved by rendering Server Components by default, minimizing client-side javascript, optimizing images, and dynamically serving optimized SEO meta tags from a single configuration file.

4. Quick Start: Launch Your Project in 60 Seconds

Local Setup

Getting started is simple. Clone the repository, install dependencies, copy environment variables, and run:

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

Open http://localhost:3000 to see your app running locally.

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

[!NOTE]
For production deployments, set NEXT_PUBLIC_DEMO_MODE=false or remove the self-contained src/features/auth/demo/ module.

Docker Setup

Run the application locally via Docker:

cp .env.example .env
docker build -t next-elite .
docker run --rm --env-file .env -p 3000:3000 next-elite
Enter fullscreen mode Exit fullscreen mode

Or using Docker Compose:

docker compose up --build
Enter fullscreen mode Exit fullscreen mode

View Available Scripts & CLI Commands

Command Description
npm run dev Start the dev server (Turbopack)
npm run build Production build
npm run start Start the production server
npm run analyze Build with @next/bundle-analyzer
npm run typecheck tsc --noEmit
npm run lint ESLint + Prettier check
npm run lint:fix Auto-fix ESLint + Prettier
npm run knip Detect unused files / exports / dependencies
npm run check typecheck + lint + knip + tests (CI gate)
npm run test Vitest run
npm run test:watch Vitest watch
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

Architecture & Request Flow

Next Elite separates server-side security checks from client-side interactive components. Here is how a request flows:

Next Elite Architecture Flow

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

🔐 Type-Safe RBAC & BetterAuth

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

View Auth & RBAC Usage Example

// Server Component example
import { requirePermission } from '@/features/auth/rbac/require';

const AdminDashboardPage = async () => {
  // Guard the page on the server. If fails, it automatically redirects or errors.
  const user = await requirePermission('dashboard.view:admin');
  return <h1>Welcome {user.email}</h1>;
};

export default AdminDashboardPage;
Enter fullscreen mode Exit fullscreen mode

Next Elite utilizes Next.js Parallel Routes to clean up role-agnostic layouts. The routing structure mounts specific slots based on the user's role:

src/app/(protected)/
  ├── @admin/dashboard/     # Admin dashboard slot
  ├── @user/dashboard/      # User dashboard slot
  └── layout.tsx            # Dynamically renders the correct dashboard
Enter fullscreen mode Exit fullscreen mode

Adding a New Role

  1. Append the role to the UserRole union in src/features/auth/rbac/permissions.ts.
  2. Map permissions for the role in src/features/auth/rbac/roles.ts.
  3. 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 configurations that force prefixes like /en/ or /es/ in the URL (which can clutter routes and create duplicate routing configurations), Next Elite implements zero-prefix cookie-based locales.

Adding a Language

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

📈 Site & SEO Configuration

SEO parameters, sitemap generation, and manifests are driven by src/features/site/site.config.json as 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 + React 19 boilerplate with i18n, RBAC and BetterAuth."
}
Enter fullscreen mode Exit fullscreen mode

📡 API client & Data Validation

The custom apiFetch client in src/libs/api-client.ts uses ofetch and integrates with Zod validation. This guarantees type-safe request schemas and API responses.

View API Fetch & Form Usage Examples

API Request:

// src/features/users/api.ts
export async function getUsers(): Promise {
  return apiFetch('/users', { schema: userListSchema });
}
Enter fullscreen mode Exit fullscreen mode

Client Form with Zod validation:

'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: '' },
});
Enter fullscreen mode Exit fullscreen mode

6. Clean Feature-Based Directory Structure

Next Elite uses a Feature-Based (Vertical Slice) Architecture under src/features/. Each folder contains its own API requests, components, hooks, schemas, and routing logic. Shared utilities live under src/libs/ or src/components/shared/.

Expand Directory Structure View

.
├── .github/
│   └── workflows/            # CI: lint, typecheck, tests, Playwright
├── config/                   # Vitest config &amp; test setup
├── e2e/                      # Playwright E2E tests
├── messages/                 # Translation JSONs (en, bn, ar, fr, es, zh)
├── public/                   # Static assets
├── src/
│   ├── app/                  # Next.js App Router Pages &amp; Layouts
│   │   ├── (auth)/           # Auth views (login, register, reset password)
│   │   ├── (public)/         # Public landing and marketing routes
│   │   └── (protected)/      # Protected area rendering slot-based RBAC
│   ├── components/
│   │   ├── shared/           # Cross-app reusable components
│   │   └── ui/               # shadcn UI primitive elements
│   ├── features/             # Self-contained feature folders (vertical slices)
│   │   ├── auth/             # BetterAuth configurations &amp; role management
│   │   ├── i18n/             # next-intl bootstrap and hooks
│   │   ├── site/             # Site details &amp; SEO configuration
│   │   └── users/            # Example modular API feature
│   └── libs/                 # Core wrapper clients (api-client, logger, env)
└── package.json              # Script configurations &amp; dependencies
Enter fullscreen mode Exit fullscreen mode

7. Architectural Caveats: What Next Elite is NOT

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

  1. No Database Bundled: There is no Prisma, Drizzle, Postgres, or MongoDB setup. Next Elite is built to communicate with an external API. If you need local mock data or a quick mock DB, you'll need to hook that up.
  2. 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, we recommend mapping roles on your main database and API layer.
  3. Cookie-Based i18n: By storing user localization choice in a cookie rather than a path-prefix (like /en/dashboard), routes remain simpler, but path-prefixed SEO indexing for multiple locales will require a custom router setup.
  4. Local BetterAuth Sessions: By default, session keys run locally. A session adapter is recommended for production setups using multiple server instances.

8. Production Checklist: Going Live

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

  1. Configure Auth Secrets: Set BETTER_AUTH_SECRET (at least 32 characters long) in your hosting dashboard.
  2. Add a Session Storage Adapter: BetterAuth requires an external database or Redis adapter to manage server sessions in multi-instance production environments.
  3. Disable Demo Mode: Set NEXT_PUBLIC_DEMO_MODE=false or completely delete the src/features/auth/demo/ folder.
  4. Link Your API: Implement your backend endpoints or update NEXT_PUBLIC_APP_URL to point to your live REST/GraphQL/BFF service.
  5. Update SEO Metadata: Change site.config.json with your project domain name, official OG image, and app description.
  6. Activate Logging & Error Tracing: Add Sentry and Pino configurations to track errors in real-time.

9. Contributing & Open Source

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

  1. Fork the repository and create a feature branch (git checkout -b feat/my-feature).
  2. Ensure linting, types, and tests pass by running npm run check.
  3. Follow the Conventional Commits standard (which is automatically validated via Lefthook pre-commit hooks).
  4. Create a Pull Request back to the main branch.

If this starter boilerplate saves you development time, consider giving the repo a star! ⭐

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

Top comments (0)