main
This commit is contained in:
Harun CAN
341
README.md
Normal file
341
README.md
Normal file
@@ -0,0 +1,341 @@
|
||||
# 🚀 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.
|
||||
Reference in New Issue
Block a user