Next Elite

An open-source, frontend-first Next.js boilerplate built for an API-driven workflow, no attached database required. It's designed to consume external backends (REST, GraphQL, or BFF) while giving you a polished, production-ready starting point out of the box with pre-built auth layouts, role-based dashboard layouts, and 50+ custom & reusable UI components.

🚀 Live Demo · 📦 Use this Template · 🐛 Report Bug · ✨ Request Feature

https://github.com/user-attachments/assets/123e879c-1d27-4781-a423-e8605505ce0a

Next Elite	50+ Custom Components
Auth Layouts	Dashboard Layouts

Highlights & Features:

• ⚡ Next.js 16.3 + React 19 - Fast App Router, Turbopack, and Server Actions
• 🔥 TypeScript 6 - End-to-end type safety across components and routes
• ✨ Oxlint + Oxfmt - Blazing-fast linting & formatting with Lefthook pre-commit hooks
• 🤖 Next.js Best Practices - Modular architecture, standalone Docker build, and performance optimizations
• 🔐 Authentication & RBAC - Email/Password & Google OAuth via BetterAuth with permission-based RBAC
• 🖼️ Auth & Dashboard Layouts - Split-pane auth layout & role-based dashboard layout with fixed sidebar navigation
• 🎨 50+ Custom & Reusable UI Components - Accessible shadcn/ui primitives built with Tailwind CSS v4 & Radix UI
• 📚 Type-Safe i18n - Cookie-based multi-language support (6 locales, LTR + RTL) powered by next-intl
• 📝 SEO & PWA Suite - OpenGraph metadata, dynamic sitemap, robots.txt, and web manifest
• 🧪 Comprehensive Testing - Unit/component testing with Vitest and E2E testing with Playwright

🚀 One-click Deploy to Vercel

• Testing Suite - Unit/component testing with Vitest and React Testing Library, and E2E testing with Playwright.
• 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.

📈 Lighthouse Report

⚡ Quick Start

Prerequisites

• Node.js 22.12 or later
• npm

Local Setup

1. Clone the repository and navigate into it:

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

1. Install dependencies:

npm install

1. Set up your environment variables:

cp .env.example .env

1. 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 | [email protected] | 12345678 | | Admin | [email protected] | 12345678 |

[!NOTE]

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

Docker & Production Containerization

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

Quick Start with Docker

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

Multi-Arch Deploy (ARM64 + AMD64)

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.

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

🧩 Architecture Overview

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
classDef userNode fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
    classDef serverNode fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#334155;
    classDef securityNode fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
    classDef authNode fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#78350f;
    classDef hookNode fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a;
    classDef apiNode fill:#fdf4ff,stroke:#d946ef,stroke-width:2px,color:#701a75;
class User userNode;
    class Page serverNode;
    class Guard securityNode;
    class Auth authNode;
    class Hook hookNode;
    class Api apiNode;
style Server fill:none,stroke:#cbd5e1,stroke-width:1px
    style Client fill:none,stroke:#cbd5e1,stroke-width:1px

How a request flows:

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 → your API (REST/GraphQL/BFF).

// 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;

'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<LoginInput>({
  resolver: zodResolver(loginSchema),
  defaultValues: { email: '', password: '' },
});

🗂️ Project Structure

.
├── .github/
│   ├── workflows/            CI: check.yml + playwright.yml
│   └── renovate.json         Dependency updates
├── config/                   vitest.config.ts, vitest.setup.ts
├── e2e/                      Playwright specs + playwright.config.ts
├── messages/                 next-intl translations (en, bn, ar, fr, es, zh)
├── public/                   Static assets
├── tests/                    Vitest specs (auth, i18n)
├── components.json           shadcn/ui CLI config
├── .oxlintrc.json            Oxlint rules (Next.js, TypeScript, React, Unicorn)
├── .oxfmtrc.json             Oxfmt formatter config (Tailwind class sorting)
├── knip.json
├── next.config.mjs
├── package.json              scripts + Commitlint config
├── package-lock.json         npm lockfile (single source of truth)
├── proxy.ts                  Next.js 16 network proxy (pass-through)
├── tsconfig.json
├── lefthook.yml              Git hooks (pre-commit, commit-msg, pre-push)
├── src/
│   ├── app/                  App Router
│   │   ├── (auth)/           Login, register, & reset-password pages
│   │   ├── (public)/         Marketing pages (home, ui-components)
│   │   ├── (protected)/      Authenticated area + RBAC
│   │   │   ├── @admin/       Admin slots (dashboard, profile, settings)
│   │   │   ├── @user/        User slots (dashboard, profile, settings)
│   │   │   └── layout.tsx    Picks slot based on permissions
│   │   ├── api/              Route handlers (BetterAuth, health)
│   │   ├── styles/           Design system tokens, base CSS, & animations
│   │   ├── fonts.ts          Inter typography configuration
│   │   ├── layout.tsx        Root layout, SEO, Inter font, providers
│   │   ├── providers.tsx     Theme + Auth + TanStack Query
│   │   ├── manifest.ts       Web app manifest
│   │   ├── robots.ts         robots.txt
│   │   └── sitemap.ts        Dynamic sitemap
│   ├── components/
│   │   ├── auth/             Auth forms & particle animation canvas
│   │   ├── icons/            Centralized SVG icon components & barrel export
│   │   ├── layout/           App shell, navigation sidebars, topbar & branding
│   │   ├── pages/            Landing page & UI components page modules
│   │   ├── shared/           User dropdown, text links, theme & language controls
│   │   └── ui/               50+ shadcn/ui primitives
│   ├── config/               App navigation & feature flags configuration
│   ├── features/             Feature modules (vertical slices)
│   │   ├── auth/             BetterAuth + RBAC
│   │   │   ├── hooks/        Auth provider + useAuth hook
│   │   │   ├── demo/         Self-contained demo module (delete for prod)
│   │   │   ├── rbac/         permissions, roles, can, require
│   │   │   └── schemas/      Zod login + register schemas
│   │   ├── i18n/             next-intl config (routing, request, actions)
│   │   └── site/             siteConfig + locale utilities
│   ├── hooks/                Shared React hooks (useMobile, etc.)
│   ├── libs/                 Cross-cutting infra (env, query-client, utils)
│   ├── instrumentation.ts    Server Sentry init
│   ├── instrumentation-client.ts  Client Sentry init
│   └── global.d.ts           next-intl type augmentation
└── ...

⚙️ Configuration

Environment variables

Every variable is documented in .env.example and validated by src/libs/env.ts (T3 Env).

Site & SEO configuration

src/features/site/site.config.json is the single source of truth for SEO metadata, dynamic sitemaps, localized routes, and 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.3 + React 19 boilerplate with i18n, RBAC and BetterAuth."
}

🧪 Development & Testing

View Available Scripts

| 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 analyze | Build with @next/bundle-analyzer | | 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 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 |

🎯 When to Use

Next Elite is best for:

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

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

🤝 Contributing

Contributions to Next-Elite are welcome.

1. Fork the repository and create a branch from main.
2. Use clear branch names such as feat/..., fix/..., or docs/....
3. Run npm run check before submitting your changes.
4. Follow Conventional Commits.
5. Open a Pull Request with a clear description of your changes.

📜 License

MIT LICENSE

⭐ Support Next-Elite

If you find Next-Elite useful, consider giving it a ⭐ Star on GitHub.

Thanks for reading!