KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

Next-Elite

★ 103 Open GitHub ↗

An open source production-ready Next.js starter kit: frontend-first + api-driven, next.js 16 + react 19, better-auth, rbac, i18n, shadcn, tailwind v4, oxlint, oxfmt, playwright, vitest, seo + pwa.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<a href="https://next-elite-boilerplate.vercel.app/">
 <img alt="Next Elite - Production-Ready SaaS Boilerplate" src="https://next-elite-boilerplate.vercel.app/Nextjs-Elite-OG-Image.webp" />
 <h1 align="center">Next Elite</h1>
</a>

A production-ready, frontend-first Next.js boilerplate with i18n, RBAC, BetterAuth, and a polished DX out of the box.

<a href="https://next-elite-boilerplate.vercel.app/">Live Demo</a> ·
 <a href="https://github.com/salmanshahriar/Next-Elite/generate">Use this Template</a> ·
 <a href="https://github.com/salmanshahriar/Next-Elite/issues">Report Bug</a> ·
 <a href="https://github.com/salmanshahriar/Next-Elite/issues">Request Feature</a>

<a href="#introduction">Introduction</a> ·
 <a href="#one-click-deploy">One-click Deploy</a> ·
 <a href="#tech-stack--features">Tech Stack + Features</a> ·
 <a href="#quick-start">Quick Start</a> ·
 <a href="#architecture-overview">Architecture Overview</a> ·
 <a href="#configuration">Configuration</a>

## Introduction

Next Elite is a frontend-first Next.js 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 feature-based, offering a polished developer experience (DX), built-in role-based access control (RBAC), type-safe internationalization (i18n), and is optimized for speed, SEO, and developer productivity.

Includes **40+ custom & reusable ui components** built on shadcn/ui.

## One-click Deploy

You can deploy this template to Vercel with the button below:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/salmanshahriar/Next-Elite)

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

## Tech Stack + Features

### Frameworks & Core

- **Next.js 16 (App Router)** - 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** - 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

- **Tailwind CSS 4** - Utility-first styling with `@tailwindcss/postcss` and `tw-animate-css`.
- **shadcn/ui** - Highly customizable UI components built with Tailwind CSS, Radix UI, and CVA.
- **Theme Support** - Easy light/dark mode transitions via theme toggle.

### 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.

### Observability & Infrastructure

- **Sentry Integration** - Complete error tracking and performance instrumentation for client and server.
- **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** - [Oxlint](https://oxc.rs/docs/guide/usage/linter) and [Oxfmt](https://oxc.rs/docs/guide/usage/formatter) for fast linting and formatting, plus Knip for dead code/dependency hygiene.
- **Git Hook Automation** - Lefthook pre-commit hooks (oxlint + oxfmt) and Commitlint to maintain codebase quality.

## Lighthouse report

## Quick Start

### Prerequisites

- Node.js **22.12** or later
- **npm**

### Local Setup

1. Clone the repository and navigate into it:
   ```bash
   git clone https://github.com/salmanshahriar/Next-Elite.git
   cd Next-Elite
   ```
2. Install dependencies:
   ```bash
   npm install
   ```
3. Set up your environment variables:
   ```bash
   cp .env.example .env
   ```
4. Start the development server:
   ```bash
   npm run dev
   ```

Open [http://localhost:6767](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` |

> [!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:

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

Or using Docker Compose:

```bash
docker compose up --build
```

### 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:

```bash
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, etc.).

### Dokploy Deployment

This template is ready for [Dokploy](https://dokploy.com) - 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.

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

## 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.

```mermaid
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).

<details>
<summary>View Auth & RBAC Usage</summary>

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

</details>

<details>
<summary>View Forms Usage (React Hook Form + Zod)</summary>

```tsx
'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: '' },
});
```

</details>

## Project Structure

<details>
<summary>View Directory Structure</summary>

```
.
├── .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)
├── src/
│   ├── app/                  App Router
│   │   ├── (auth)/           Login & auth pages
│   │   ├── (public)/         Marketing pages (home, ui-components)
│   │   ├── (protected)/      Authenticated area + RBAC
│   │   │   ├── @admin/       Admin dashboard slot
│   │   │   ├── @user/        User dashboard slot
│   │   │   └── layout.tsx    Picks slot based on permissions
│   │   ├── api/              Route handlers (BetterAuth, health)
│   │   ├── layout.tsx        Root layout, SEO, providers
│   │   ├── providers.tsx     Theme + Auth + TanStack Query
│   │   ├── manifest.ts       Web app manifest
│   │   ├── robots.ts         robots.txt
│   │   └── sitemap.ts        Dynamic sitemap
│   ├── components/
│   │   ├── shared/           App-level shared components
│   │   ├── icons/            Icon components
│   │   └── ui/               shadcn/ui primitives
│   ├── features/             Feature modules (vertical slices)
│   │   ├── auth/             BetterAuth + RBAC
│   │   │   ├── lib/          auth + auth-client (BetterAuth singletons)
│   │   │   ├── server/       Server-only helpers (getCurrentUser)
│   │   │   ├── hooks/        Auth provider + useAuth hook
│   │   │   ├── components/   Login form, register form
│   │   │   ├── 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)
│   │   ├── navigation/       Header, sidebar, topbar, top loader
│   │   ├── site/             siteConfig + locale utilities
│   │   └── theme/            Theme provider + toggle
│   ├── hooks/                Cross-feature hooks (use-scroll)
│   ├── 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
└── ...
```

</details>

## Configuration

### Environment variables

Every variable is documented in [`.env.example`](.env.example) and validated 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.

### Site & SEO configuration

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

```json
{
  "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."
}
```

<details>
<summary>Adding a Language</summary>

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

</details>

<details>
<summary>Adding a Role</summary>

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)/@<role>/...` - and update `(protected)/layout.tsx` to render it based on permissions.

</details>

## Development & Testing

<details>
<summary>View Available Scripts</summary>

| Command                           | Description                              |
| --------------------------------- | ---------------------------------------- |
| `npm run dev`                     | Start the dev server (port 6767)         |
| `npm run build`                   | Production build                         |
| `npm run start`                   | Start the production server              |
| `npm run analyze`                 | Build with `@next/bundle-analyzer`       |
| `npm run check`                   | CI gate: typecheck + lint + knip + tests |
| `npm run lint:fix`                | Auto-fix with Oxlint + Oxfmt             |
| `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                   |

</details>

<details>
<summary>Editor Setup</summary>

Install the [Oxc VS Code extension](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) (`oxc.oxc-vscode`) for format-on-save and Oxlint fix-on-save. Project settings in `.vscode/settings.json` are preconfigured.

</details>

<details>
<summary>Testing Details</summary>

- **Unit / component:** Vitest + React Testing Library (`config/vitest.config.ts`). Use `renderWithProviders` from `@tests/utils/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/` 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.

</details>

<details>
<summary>CI/CD Pipeline</summary>

- `.github/workflows/check.yml` - typecheck → lint → knip → unit tests → build, on every push and PR.
- `.github/workflows/playwright.yml` - build → Playwright E2E (Chromium, production server).
- `.github/renovate.json` - groups non-major dependency updates and automerges patches.

</details>

## 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.

It is probably overkill for:

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

## Contributing

1. Fork & branch from `main` (`feat/...`, `fix/...`, etc.)
2. Ensure `npm run check` passes locally.
3. Use Conventional Commits.
4. Open a pull request.

## License

MIT [LICENSE](LICENSE)

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

[![GitHub stars](https://img.shields.io/github/stars/salmanshahriar/Next-Elite?style=social)](https://github.com/salmanshahriar/Next-Elite/stargazers)

</div>

Next-Elite

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README