# ViraStack — Next.js 16 Boilerplate (Full)

> Production-ready Next.js 16 + React 19 + Tailwind CSS v4 boilerplate designed for scalability, performance, and developer happiness. Minimal by design: no built-in Auth or Testing to keep the core flexible. Strong conventions, internationalization, and AI-native rules for reliable agent collaboration.

ViraStack - Next.js Boilerplate provides a clean, scalable baseline for modern App Router projects:

- Next.js 16 with Server/Client Components, streaming, metadata, and file-system routing under `src/app/[locale]`
- React 19 concurrency features
- Tailwind CSS v4 for styling with a small, fast pipeline
- TypeScript-first, Zod runtime validation, and `@t3-oss/env-nextjs` for environment schemas
- TanStack Query for server-state; Zustand for small global client state
- next-intl for i18n (locale folders, message catalogs, and formatters)
- Next Themes (light/dark), Lucide icons, Sonner for notifications, Google Analytics support
- Code quality: ESLint 9, Prettier 3, Husky, lint-staged, 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

Important notes:
- Minimalist by intent: No Auth/Test scaffolds included; choose and integrate your preferred solutions.
- Customization: search for `FIXME:` tags (env, robots, sitemap, site config, SEO, i18n, api). Prefer path aliases: `@/ui`, `@/widgets`, `@/hooks`, `@/data`, `@/schemas`, `@/layouts`.
- HTTP uses Axios through helpers in `src/lib/api.ts` (`get/post/put/del`).
- All user-facing strings should be sourced from `src/messages/*.json`.
- Shadcn UI primitives live under `src/components/ui` and should remain unmodified.

## Project Files
- [`src/app/[locale]/layout.tsx`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/app/%5Blocale%5D/layout.tsx): Root layout (required; wraps entire app)
- [`src/app/[locale]/page.tsx`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/app/%5Blocale%5D/page.tsx): Home page (Server Component by default)
- [`src/app/not-found.tsx`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/app/not-found.tsx): 404 boundary UI
- [`src/app/robots.ts`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/app/robots.ts): Robots file generation
- [`src/app/sitemap.ts`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/app/sitemap.ts): Sitemap generation
- [`src/env.ts`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/env.ts): Zod-validated env variables (single source of truth)
- [`src/config/site.ts`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/config/site.ts): Site identity, URLs, socials
- [`src/config/seo.ts`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/config/seo.ts): Metadata defaults (SEO, Open Graph)
- [`src/lib/api.ts`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/lib/api.ts): Axios instance and HTTP helpers
- [`src/lib/query-client.ts`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/lib/query-client.ts): TanStack Query client setup
- [`src/hooks/use-users.ts`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/hooks/use-users.ts): Example query hook pattern
- [`src/i18n/routing.ts`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/i18n/routing.ts): i18n-aware routing helpers
- [`src/messages/en.json`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/messages/en.json): English messages
- [`src/messages/tr.json`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/messages/tr.json): Turkish messages
- [`src/providers/Providers.tsx`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/providers/Providers.tsx): Theme/Query/Intl providers
- [`src/components/ui`](https://github.com/virastack/nextjs-boilerplate/tree/main/src/components/ui): Shadcn UI primitives (do not modify)
- [`src/components/widgets`](https://github.com/virastack/nextjs-boilerplate/tree/main/src/components/widgets): High-level UI (Hero, Dashboard, etc.)
- [`src/styles/tailwind.css`](https://github.com/virastack/nextjs-boilerplate/blob/main/src/styles/tailwind.css): Tailwind v4 entry
- [`.cursor/rules`](https://github.com/virastack/nextjs-boilerplate/blob/main/.cursor/rules): Rules for AI-native development
- [`README.md`](https://github.com/virastack/nextjs-boilerplate/blob/main/README.md): Overview, structure, naming conventions

## Next.js (Core References)
- [Getting Started](https://nextjs.org/docs/app/getting-started)
- [Project Structure](https://nextjs.org/docs/app/getting-started/project-structure)
- [Layouts and Pages](https://nextjs.org/docs/app/getting-started/layouts-and-pages)
- [Linking and Navigating](https://nextjs.org/docs/app/getting-started/linking-and-navigating)
- [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components)
- [Fetching Data](https://nextjs.org/docs/app/getting-started/fetching-data)
- [Updating Data (Server Functions/Actions)](https://nextjs.org/docs/app/getting-started/updating-data)
- [Caching and Revalidating](https://nextjs.org/docs/app/getting-started/caching-and-revalidating)
- [Error Handling](https://nextjs.org/docs/app/getting-started/error-handling)
- [CSS](https://nextjs.org/docs/app/getting-started/css)
- [Image Optimization](https://nextjs.org/docs/app/getting-started/images)
- [Font Optimization](https://nextjs.org/docs/app/getting-started/fonts)
- [Route Handlers](https://nextjs.org/docs/app/getting-started/route-handlers)
- [Proxy](https://nextjs.org/docs/app/getting-started/proxy)
- [Deploying](https://nextjs.org/docs/app/getting-started/deploying)
- [Upgrading](https://nextjs.org/docs/app/getting-started/upgrading)

## Next.js (API and Conventions)
- [File-system Conventions](https://nextjs.org/docs/app/api-reference/file-conventions)
- [Dynamic Routes](https://nextjs.org/docs/app/api-reference/file-conventions/dynamic-routes)
- [Metadata, robots, sitemap](https://nextjs.org/docs/app/api-reference/file-conventions/metadata)
- [Functions and Hooks](https://nextjs.org/docs/app/api-reference/functions)
- [Configuration (next.config.js)](https://nextjs.org/docs/app/api-reference/config)
- [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack)

## Internationalization
- [Internationalization (App Router)](https://nextjs.org/docs/app/guides/internationalization)
- [next-intl docs](https://next-intl-docs.vercel.app/)
- ViraStack - Next.js Boilerplate uses locale segments under `src/app/[locale]` and JSON message catalogs under `src/messages/`.

## Styling
- [Tailwind CSS v4](https://tailwindcss.com/)
- Entry in `src/styles/tailwind.css`. Prefer utility classes; avoid inline styles.

## Data & State
- [TanStack Query](https://tanstack.com/query/latest): Server-state management and caching
- [Axios](https://axios-http.com/): HTTP client (via `src/lib/api.ts`)
- [Zustand](https://github.com/pmndrs/zustand): Lightweight client state

## Environment & Validation
- [@t3-oss/env-nextjs](https://env.t3.gg/): Type-safe environment schema
- [Zod](https://zod.dev/): Runtime validation and parsing
- Single source of truth at `src/env.ts`.

## Accessibility and Conventions
- Follow ARIA best practices; user-facing strings must come from `src/messages`.
- Naming conventions and structure are documented in the project `README.md`. Type names use PascalCase without a Type suffix (e.g. User, SiteConfig).
- For agents: read `.cursor/rules` before edits; do not modify `src/components/ui`.

## Optional
- [`src/components/layouts`](https://github.com/virastack/nextjs-boilerplate/tree/main/src/components/layouts): Header/Footer building blocks
- [`src/constants`](https://github.com/virastack/nextjs-boilerplate/tree/main/src/constants): Constants (e.g., locales, dates)
- [`src/lib/helpers`](https://github.com/virastack/nextjs-boilerplate/tree/main/src/lib/helpers): Helper functions
- [`src/types`](https://github.com/virastack/nextjs-boilerplate/tree/main/src/types): Shared type declarations (PascalCase, no Type suffix: User, SiteConfig)
- [`src/data`](https://github.com/virastack/nextjs-boilerplate/tree/main/src/data): Static sample data