Faizanahmedsy/best-nextjs-16-react-19-boilerplate

README

🚀 Super Next.js 16 Enterprise Boilerplate

Engineered, not generated.
Handcrafter, not vibe coded.

A production-grade foundation built on Next.js 16, React 19, React compiler and Tailwind v4. Designed for performance, strict type safety, and scalability.

💎 Why This Boilerplate?

This project is hand-crafted by experienced engineer to solve real-world production problems:

Zero-Bundle Layouts: Layouts render entirely on the server. Zero JavaScript sent to the client for the shell.
The "Hybrid" Network Layer:
- Server Actions for Mutations (Auth, Forms) -> No Client JS, HttpOnly Cookies.
- TanStack Query for Data Fetching (Lists, Tables) -> Caching, Deduplication.
Strict Architecture: Feature-Sliced Design (Vertical Slices) prevents "Spaghetti Code" as the app grows to 100k+ lines.
100% Lighthouse Score: Optimized images, fonts, accessibility landmarks, and scalable viewports out of the box.

🏆 Performance Benchmarks

We don't just talk about performance; we measure it. Achieved 100/100 scores on Lighthouse (Mobile) with strict accessibility standards.

🛠 Tech Stack

Framework: Next.js 16 (App Router + Turbopack)
Core: React 19 (Server Components + Actions)
Styling: Tailwind CSS v4 (OKLCH Colors + @theme directives)
UI Library: Shadcn UI (Canary / R19 Compatible)
Validation: Zod (Shared Schemas for Client/Server)
Testing: Vitest (Unit/Component) + Playwright (E2E)
Quality: ESLint (Strict), Prettier (Sorted), Husky (Git Hooks)

📂 Architecture: Feature-Sliced Design

We abandoned the traditional components/ vs pages/ mess. We use Vertical Slices where everything related to a feature lives together.

src/
├── api/                      # 🌍 Network Layer (Centralized)
│   ├── client.ts             # Type-safe Fetch Wrapper
│   ├── endpoints.ts          # API URL Registry
│   └── server-wrapper.ts     # Action Logger & Error Handler
│
├── features/                 # 📦 Vertical Slices (The Brain)
│   └── auth/
│       ├── actions/          # Server Actions (Controllers)
│       ├── components/       # Feature-specific UI
│       ├── schemas/          # Zod Schemas
│       └── types/            # TypeScript Definitions
│
├── components/               # 🧩 Global Shared UI
│   ├── ui/                   # Shadcn Primitives (Dumb)
│   └── layouts/              # App Shells
│
└── proxy.ts                  # 🛡️ Edge Middleware (Route Protection)

⚡ Developer Experience (DX)

We enforce quality so you don't have to argue about it in Code Reviews.

1. The "Smart" Server Action Hook

We don't use raw useActionState. We use a custom hook that:

Auto-toasts Success/Error messages.
Logs detailed network payloads to the Browser Console (mimicking the Network Tab for Server Actions).

// Inside any component
const [state, action, isPending] = useServerAction(loginAction);

2. Strict Linting Rules

No Arrow Components: Forces function ComponentName() {} for better stack traces.
No Relative Imports: Forces @/components/... for cleaner refactoring.
Type Safety: Strict unknown error handling in try/catch blocks.

🚀 Getting Started

This project enforces pnpm to prevent dependency hoisting issues.

# 1. Install Dependencies
pnpm install

# 2. Setup Environment
cp .env.example .env.local
# (Fill in NEXT_PUBLIC_API_URL)

# 3. Run Development Server
pnpm dev

🧪 Testing Strategy

We use a "Trophy" testing strategy.

Unit & Component Tests (Vitest)

Tests logic, Zod schemas, and UI accessibility/state.

pnpm test

End-to-End Tests (Playwright)

Tests the Real flows: Middleware redirects, Cookie setting, and full Login flows against the API.

pnpm e2e

🛡️ Authentication Flow

Form Submission: Uses React 19 action prop.
Server Action: Validates Zod -> Calls External API -> Sets HttpOnly Cookies.
Redirect: Uses highly optimized Server-Side redirect() (Status 303) for instant navigation.
Protection: proxy.ts (Middleware) checks cookies on Edge to protect /dashboard.

🤝 Contribution Guidelines

No any types. Ever.
Server Components first. Only use "use client" when interactivity is required.
Colocation. Keep styles, tests, and logic near the component using them.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Faizanahmed Saiyed

GitHub: @Faizanahmedsy
Repository: best-nextjs-16-react-19-boilerplate

Hand-crafted with obsession for quality.