342 lines
12 KiB
Markdown
342 lines
12 KiB
Markdown
# 🚀 Enterprise Next.js Boilerplate (Antigravity Edition)
|
|
|
|
[](https://nextjs.org/)
|
|
[](https://react.dev/)
|
|
[](https://chakra-ui.com/)
|
|
[](https://www.typescriptlang.org/)
|
|
[](https://next-intl-docs.vercel.app/)
|
|
|
|
> **FOR AI AGENTS & DEVELOPERS:** This documentation is structured to provide deep context, architectural decisions, and operational details to ensure seamless handover to any AI coding assistant (like Antigravity) or human developer.
|
|
|
|
---
|
|
|
|
## 🧠 Project Context & Architecture (Read Me First)
|
|
|
|
This is an **opinionated, production-ready** frontend boilerplate built with Next.js 16 App Router. It is designed to work seamlessly with the companion **typescript-boilerplate-be** NestJS backend.
|
|
|
|
### 🏗️ Core Philosophy
|
|
|
|
- **Type Safety First:** Strict TypeScript configuration. DTOs and typed API responses connect frontend to backend.
|
|
- **App Router Native:** Built entirely on Next.js App Router with Server Components and React Server Actions support.
|
|
- **i18n Native:** Localization is baked into routing, API calls, and UI components via `next-intl`.
|
|
- **Theme-First Design:** Chakra UI v3 with custom theme system for consistent, accessible UI.
|
|
- **Auth by Default:** NextAuth.js integration with JWT token management and automatic session handling.
|
|
|
|
### 📐 Architectural Decision Records (ADR)
|
|
|
|
_To understand WHY things are the way they are:_
|
|
|
|
1. **Locale-Based Routing:**
|
|
- **Mechanism:** All routes are prefixed with locale (e.g., `/tr/dashboard`, `/en/login`).
|
|
- **Implementation:** `next-intl` plugin with `[locale]` dynamic segment in `app/` directory.
|
|
- **Config:** `localePrefix: 'always'` ensures consistent URL structure.
|
|
|
|
2. **API Client with Auto-Auth & Locale:**
|
|
- **Location:** `src/lib/api/create-api-client.ts`
|
|
- **Feature:** Automatically injects JWT `Authorization` header from NextAuth session.
|
|
- **Feature:** Automatically sets `Accept-Language` header based on current locale (cookie or URL path).
|
|
- **Auto-Logout:** 401 responses trigger automatic signOut and redirect.
|
|
|
|
3. **Backend Proxy (CORS Solution):**
|
|
- **Problem:** Local development CORS issues when frontend (port 3001) calls backend (port 3000).
|
|
- **Solution:** Next.js `rewrites` in `next.config.ts` proxies `/api/backend/*` → `http://localhost:3000/api/*`.
|
|
- **Usage:** API clients use `/api/backend/...` paths in development.
|
|
|
|
4. **Provider Composition:**
|
|
- **Location:** `src/components/ui/provider.tsx`
|
|
- **Stack:** `SessionProvider` (NextAuth) → `ChakraProvider` (UI) → `ColorModeProvider` (Dark/Light) → `Toaster` (Notifications)
|
|
- **Why:** Single import in layout provides all necessary contexts.
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start for AI & Humans
|
|
|
|
### 1. Prerequisites
|
|
|
|
- **Node.js:** v20.19+ (LTS)
|
|
- **Package Manager:** `npm` (Lockfile: `package-lock.json`)
|
|
- **Backend:** Companion NestJS backend running on port 3000 (see `typescript-boilerplate-be`)
|
|
|
|
### 2. Environment Setup
|
|
|
|
```bash
|
|
cp .env.example .env.local
|
|
# Edit .env.local with your configuration
|
|
```
|
|
|
|
**Required Environment Variables:**
|
|
|
|
| Variable | Description | Example |
|
|
| --------------------------- | --------------------------------------------------------------- | --------------------------- |
|
|
| `NEXTAUTH_URL` | NextAuth callback URL | `http://localhost:3001` |
|
|
| `NEXTAUTH_SECRET` | Authentication secret (generate with `openssl rand -base64 32`) | `abc123...` |
|
|
| `NEXT_PUBLIC_API_URL` | Backend API base URL | `http://localhost:3001/api` |
|
|
| `NEXT_PUBLIC_AUTH_REQUIRED` | Require login for all pages | `true` or `false` |
|
|
|
|
### 3. Installation & Running
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm ci
|
|
|
|
# Development Mode (HTTPS enabled, port 3001)
|
|
npm run dev
|
|
|
|
# Production Build
|
|
npm run build
|
|
npm run start
|
|
```
|
|
|
|
> **Note:** Dev server runs on port 3001 with experimental HTTPS for secure cookie handling.
|
|
|
|
---
|
|
|
|
## 🌍 Internationalization (i18n) Guide
|
|
|
|
Deep integration with `next-intl` provides locale-aware routing and translations.
|
|
|
|
### Configuration
|
|
|
|
- **Supported Locales:** `['en', 'tr']`
|
|
- **Default Locale:** `tr`
|
|
- **Locale Detection:** Cookie (`NEXT_LOCALE`) → URL path → Default
|
|
|
|
### File Structure
|
|
|
|
```
|
|
messages/
|
|
├── en.json # English translations
|
|
└── tr.json # Turkish translations
|
|
|
|
src/i18n/
|
|
├── routing.ts # Locale routing configuration
|
|
├── navigation.ts # Typed navigation helpers (Link, useRouter)
|
|
└── request.ts # Server-side i18n setup
|
|
```
|
|
|
|
### Usage in Components
|
|
|
|
```tsx
|
|
// Client Component
|
|
"use client";
|
|
import { useTranslations } from "next-intl";
|
|
|
|
export function MyComponent() {
|
|
const t = useTranslations("common");
|
|
return <h1>{t("welcome")}</h1>;
|
|
}
|
|
|
|
// Navigation with Locale
|
|
import { Link } from "@/i18n/navigation";
|
|
|
|
<Link href="/dashboard">Dashboard</Link>; // Auto-prefixes with current locale
|
|
```
|
|
|
|
### Adding a New Locale
|
|
|
|
1. Add locale code to `src/i18n/routing.ts`:
|
|
```ts
|
|
export const locales = ["en", "tr", "de"]; // Add 'de'
|
|
```
|
|
2. Create `messages/de.json` with translations.
|
|
3. Update `getLocale()` in `create-api-client.ts` if needed.
|
|
|
|
---
|
|
|
|
## 🔐 Authentication System
|
|
|
|
Built on NextAuth.js with JWT strategy for seamless backend integration.
|
|
|
|
### How It Works
|
|
|
|
1. **Login:** User submits credentials → `/api/auth/[...nextauth]` → Backend validates → JWT returned.
|
|
2. **Session:** JWT stored in encrypted cookie, accessible via `useSession()` hook.
|
|
3. **API Calls:** `createApiClient()` automatically adds `Authorization: Bearer {token}` header.
|
|
4. **Auto-Refresh:** Token refreshed before expiry (managed by NextAuth).
|
|
|
|
### Protected Routes
|
|
|
|
```tsx
|
|
// Use middleware.ts or check session in layout
|
|
import { getServerSession } from "next-auth";
|
|
|
|
export default async function ProtectedLayout({ children }) {
|
|
const session = await getServerSession();
|
|
if (!session) redirect("/login");
|
|
return <>{children}</>;
|
|
}
|
|
```
|
|
|
|
### Auth Mode Toggle
|
|
|
|
Set `NEXT_PUBLIC_AUTH_REQUIRED=true` for mandatory authentication across all pages.
|
|
|
|
---
|
|
|
|
## 🎨 UI System (Chakra UI v3)
|
|
|
|
### Theme Configuration
|
|
|
|
- **Location:** `src/theme/theme.ts`
|
|
- **Font:** Bricolage Grotesque (Google Fonts, variable font)
|
|
- **Color Mode:** Light/Dark with system preference detection
|
|
|
|
### Component Organization
|
|
|
|
```
|
|
src/components/
|
|
├── ui/ # Chakra UI wrapper components
|
|
│ ├── provider.tsx # Root provider (Session + Chakra + Theme)
|
|
│ ├── color-mode.tsx # Dark/Light mode toggle
|
|
│ ├── feedback/ # Toaster, alerts, etc.
|
|
│ └── ...
|
|
├── layout/ # Page layout components (Header, Sidebar, Footer)
|
|
├── auth/ # Authentication forms and guards
|
|
└── site/ # Site-specific feature components
|
|
```
|
|
|
|
### Toast Notifications
|
|
|
|
```tsx
|
|
import { toaster } from "@/components/ui/feedback/toaster";
|
|
|
|
// Success toast
|
|
toaster.success({
|
|
title: "Saved!",
|
|
description: "Changes saved successfully.",
|
|
});
|
|
|
|
// Error toast
|
|
toaster.error({ title: "Error", description: "Something went wrong." });
|
|
```
|
|
|
|
---
|
|
|
|
## 📡 API Integration
|
|
|
|
### Creating API Clients
|
|
|
|
```tsx
|
|
// src/lib/api/auth/login/queries.ts
|
|
import { createApiClient } from "../create-api-client";
|
|
|
|
const api = createApiClient("/api/backend/auth");
|
|
|
|
export const loginUser = async (data: LoginDto) => {
|
|
const response = await api.post("/login", data);
|
|
return response.data;
|
|
};
|
|
```
|
|
|
|
### React Query Integration
|
|
|
|
```tsx
|
|
import { useQuery, useMutation } from "@tanstack/react-query";
|
|
|
|
// Query hook
|
|
export const useUsers = () =>
|
|
useQuery({
|
|
queryKey: ["users"],
|
|
queryFn: () => apiClient.get("/users"),
|
|
});
|
|
|
|
// Mutation hook
|
|
export const useCreateUser = () =>
|
|
useMutation({
|
|
mutationFn: (data: CreateUserDto) => apiClient.post("/users", data),
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 📂 System Map (Directory Structure)
|
|
|
|
```
|
|
src/
|
|
├── app/ # Next.js App Router
|
|
│ ├── [locale]/ # Locale-prefixed routes
|
|
│ │ ├── (auth)/ # Auth pages (login, register)
|
|
│ │ ├── (site)/ # Main site pages
|
|
│ │ ├── (error)/ # Error pages
|
|
│ │ ├── layout.tsx # Root layout with providers
|
|
│ │ └── page.tsx # Home page
|
|
│ └── api/ # Next.js API routes
|
|
│ └── auth/ # NextAuth endpoints
|
|
├── components/ # React components
|
|
│ ├── ui/ # Chakra UI wrappers & base components
|
|
│ ├── layout/ # Layout components (Header, Sidebar)
|
|
│ ├── auth/ # Auth-related components
|
|
│ └── site/ # Feature-specific components
|
|
├── config/ # App configuration
|
|
├── hooks/ # Custom React hooks
|
|
├── i18n/ # Internationalization setup
|
|
├── lib/ # Utilities & services
|
|
│ ├── api/ # API clients (organized by module)
|
|
│ │ ├── auth/ # Auth API (login, register)
|
|
│ │ ├── admin/ # Admin API (roles, users)
|
|
│ │ └── create-api-client.ts # Axios factory with interceptors
|
|
│ ├── services/ # Business logic services
|
|
│ └── utils/ # Helper functions
|
|
├── theme/ # Chakra UI theme configuration
|
|
├── types/ # TypeScript type definitions
|
|
└── proxy.ts # API proxy utilities
|
|
|
|
messages/ # Translation JSON files
|
|
public/ # Static assets
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 Testing & Development
|
|
|
|
### Available Scripts
|
|
|
|
```bash
|
|
npm run dev # Start dev server (HTTPS, port 3001)
|
|
npm run build # Production build
|
|
npm run start # Start production server
|
|
npm run lint # Run ESLint
|
|
```
|
|
|
|
### Development Tools
|
|
|
|
- **React Compiler:** Enabled for automatic optimization.
|
|
- **Top Loader:** Visual loading indicator for route transitions.
|
|
- **ESLint + Prettier:** Consistent code formatting.
|
|
|
|
---
|
|
|
|
## 🛠️ Troubleshooting (Known Issues)
|
|
|
|
**1. HTTPS Certificate Warnings in Development**
|
|
|
|
- **Context:** Dev server uses `--experimental-https` for secure cookies.
|
|
- **Fix:** Accept the self-signed certificate warning in your browser.
|
|
|
|
**2. Backend Connection Refused**
|
|
|
|
- **Fix:** Ensure NestJS backend is running on port 3000.
|
|
- **Check:** Run `curl http://localhost:3000/api/health` to verify.
|
|
|
|
**3. Session Not Persisting**
|
|
|
|
- **Fix:** Ensure `NEXTAUTH_SECRET` is set and consistent between restarts.
|
|
- **Fix:** Check that cookies are not blocked by browser settings.
|
|
|
|
**4. Locale Not Detected**
|
|
|
|
- **Context:** Default falls back to `tr` if cookie/URL detection fails.
|
|
- **Fix:** Clear `NEXT_LOCALE` cookie and refresh.
|
|
|
|
---
|
|
|
|
## 🔗 Related Projects
|
|
|
|
- **Backend:** [typescript-boilerplate-be](../typescript-boilerplate-be) - NestJS backend with Prisma, JWT auth, and i18n.
|
|
|
|
---
|
|
|
|
## 📃 License
|
|
|
|
This project is proprietary and confidential.
|