# Nizam — Next.js 16 Boilerplate

> Production-ready Next.js 16 + React 19 + Tailwind CSS v4 boilerplate designed for scalability, performance, and developer happiness. It intentionally omits Authentication and Testing scaffolds to keep the core minimal and let developers choose their preferred solutions.

Nizam is built with the App Router and embraces modern Next.js patterns: Server/Client Components, streaming, metadata, and internationalization. It includes well-structured folders, type-safe env validation with Zod, TanStack Query for data fetching, and opinionated UI building blocks. For AI-native development, this repo includes a `.cursor/rules` file that encodes coding standards and conventions so agents can collaborate effectively.

- Tech stack: Next.js 16, React 19, Tailwind CSS v4, TypeScript 5
- Data & state: TanStack Query 5, lightweight state with Zustand
- i18n: next-intl with locale-aware routing under `src/app/[locale]`
- Env: `@t3-oss/env-nextjs` + Zod in `src/env.ts`
- Philosophy: “lightweight core” — no Auth/Test by default; add what you need
- Tooling: ESLint 9, Prettier 3, Husky, Knip; Bundler Analyzer; absolute imports (`@` prefix); SEO and lighthouse-focused
- AI-native: `llms.txt` & `llms-full.txt` in `/public` plus `.cursor/rules` for agent collaboration

## Docs
- [Repository (GitHub)](https://github.com/omergulcicek/nizam): Source code and issues
- [README](https://github.com/omergulcicek/nizam/blob/main/README.md): Features, structure, and conventions

## Key Files & Entry Points
- [`src/app/[locale]/layout.tsx`](https://github.com/omergulcicek/nizam/blob/main/src/app/%5Blocale%5D/layout.tsx): Root layout (App Router)
- [`src/app/[locale]/page.tsx`](https://github.com/omergulcicek/nizam/blob/main/src/app/%5Blocale%5D/page.tsx): Home page with locale segment
- [`src/app/not-found.tsx`](https://github.com/omergulcicek/nizam/blob/main/src/app/not-found.tsx): 404 boundary
- [`src/app/robots.ts`](https://github.com/omergulcicek/nizam/blob/main/src/app/robots.ts): Robots configuration
- [`src/app/sitemap.ts`](https://github.com/omergulcicek/nizam/blob/main/src/app/sitemap.ts): Sitemap generation
- [`src/env.ts`](https://github.com/omergulcicek/nizam/blob/main/src/env.ts): Zod-validated environment schema (single source of truth)
- [`src/config/site.ts`](https://github.com/omergulcicek/nizam/blob/main/src/config/site.ts): Site config (name, URL, socials)
- [`src/config/seo.ts`](https://github.com/omergulcicek/nizam/blob/main/src/config/seo.ts): Metadata and SEO defaults
- [`src/lib/api.ts`](https://github.com/omergulcicek/nizam/blob/main/src/lib/api.ts): Axios instance and `get/post/put/del` helpers
- [`src/providers/Providers.tsx`](https://github.com/omergulcicek/nizam/blob/main/src/providers/Providers.tsx): App-wide providers (Theme, Query, Intl)

## Internationalization
- [`src/i18n/routing.ts`](https://github.com/omergulcicek/nizam/blob/main/src/i18n/routing.ts): Locale-aware routing helpers
- [`src/messages/en.json`](https://github.com/omergulcicek/nizam/blob/main/src/messages/en.json): English translations
- [`src/messages/tr.json`](https://github.com/omergulcicek/nizam/blob/main/src/messages/tr.json): Turkish translations

## Data Fetching & State
- [`src/hooks/use-users.ts`](https://github.com/omergulcicek/nizam/blob/main/src/hooks/use-users.ts): Example TanStack Query hook
- [`src/stores/counter.ts`](https://github.com/omergulcicek/nizam/blob/main/src/stores/counter.ts): Example Zustand store
- [`src/lib/query-client.ts`](https://github.com/omergulcicek/nizam/blob/main/src/lib/query-client.ts): Query client setup

## UI & Design System
- [`src/components/ui`](https://github.com/omergulcicek/nizam/tree/main/src/components/ui): Shadcn-based UI primitives (keep as-is)
- [`src/components/widgets`](https://github.com/omergulcicek/nizam/tree/main/src/components/widgets): Higher-level UI (Hero, Dashboard, etc.)
- [`src/styles/tailwind.css`](https://github.com/omergulcicek/nizam/blob/main/src/styles/tailwind.css): Tailwind v4 entry

## Customization & Imports
- Search the project for `FIXME:` tags to find customization points (env, robots, sitemap, site config, SEO, i18n, api).
- Prefer short path aliases: `@/ui`, `@/widgets`, `@/hooks`, `@/data`, `@/schemas`, `@/layouts`.

## AI‑Native Development
- [`.cursor/rules`](https://github.com/omergulcicek/nizam/blob/main/.cursor/rules): Project rules for agents (naming, structure, a11y, styling). Keep aligned with README. Type names: PascalCase without Type suffix (e.g. User, SiteConfig). Critical for consistent, reliable agent edits.

## External References
- [Next.js 16 Docs](https://nextjs.org/docs): App Router, Server/Client Components, routing, metadata, images, fonts
- [React 19](https://react.dev/): Modern React APIs and RSC foundations
- [Tailwind CSS v4](https://tailwindcss.com/): Latest design tokens & utility-first styling
- [TanStack Query](https://tanstack.com/query/latest): Server-state syncing & caching
- [next-intl](https://next-intl-docs.vercel.app/): i18n & formatting
- [@t3-oss/env-nextjs](https://env.t3.gg/): Type-safe env validation with Zod
- [Zod](https://zod.dev/): Runtime validation and parsing

## Optional
- [`src/components/layouts`](https://github.com/omergulcicek/nizam/tree/main/src/components/layouts): Header/Footer scaffolding
- [`src/constants`](https://github.com/omergulcicek/nizam/tree/main/src/constants): Global constants (i18n, date)
- [`src/lib/helpers`](https://github.com/omergulcicek/nizam/tree/main/src/lib/helpers): Utility helpers
- [`src/types`](https://github.com/omergulcicek/nizam/tree/main/src/types): Centralized TypeScript types (PascalCase, no Type suffix: User, SiteConfig)
- [`src/data`](https://github.com/omergulcicek/nizam/tree/main/src/data): Static data sets for examples