# Idea Guru Template

A modern Next.js starter template with a curated tech stack, designed for rapid development of full-featured web applications.

## Tech Stack

| Category | Technology |
| --- | --- |
| Framework | [Next.js 16](https://nextjs.org/) (App Router) |
| Language | [TypeScript 5](https://www.typescriptlang.org/) |
| Styling | [Tailwind CSS 4](https://tailwindcss.com/) |
| UI Components | [shadcn/ui](https://ui.shadcn.com/) (base-nova style, powered by `@base-ui/react`) |
| State Management | [Zustand 5](https://zustand.docs.pmnd.rs/) (client state) + [TanStack Query 5](https://tanstack.com/query) (server state) |
| Forms | [React Hook Form](https://react-hook-form.com/) + [Zod 4](https://zod.dev/) |
| HTTP Client | [Axios](https://axios-http.com/) with interceptors |
| Animation | [Framer Motion](https://motion.dev/) |
| Icons | [Lucide React](https://lucide.dev/) |
| Auth | [NextAuth.js v5](https://authjs.dev/) |
| i18n | [next-intl](https://next-intl.dev/) |
| Theming | [next-themes](https://github.com/pacocoursey/next-themes) |
| Toasts | [Sonner](https://sonner.emilkowal.dev/) |
| Dates | [date-fns](https://date-fns.org/) |
| Monitoring | [Sentry](https://sentry.io/) |
| Linting | ESLint (flat config) + Prettier + `prettier-plugin-tailwindcss` |

## Getting Started

```bash
# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start

# Lint code
pnpm lint
```

Open [http://localhost:3000](http://localhost:3000) to view the app.

## Project Structure

```
src/
├── app/                    # Next.js App Router (pages & layouts)
│   ├── globals.css         # Global styles & shadcn/ui theme variables
│   ├── layout.tsx          # Root layout with providers
│   └── page.tsx            # Home page
├── components/
│   ├── ui/                 # shadcn/ui components (Button, Card, Input, etc.)
│   ├── layout/             # Layout components (Header, Footer, etc.)
│   └── common/             # Reusable app-level components
├── hooks/                  # Custom React hooks
│   ├── use-example.query.ts  # Example TanStack Query hook
│   └── use-media-query.ts    # Responsive media query hook
├── lib/                    # Utility modules
│   ├── axios.ts            # Axios instance with auth & error interceptors
│   ├── env.ts              # Zod-validated environment variables
│   ├── query-client.ts     # TanStack Query client configuration
│   ├── utils.ts            # cn() utility for conditional classNames
│   └── validations.ts      # Zod schemas for form validation
├── providers/              # React context providers (Theme, QueryClient)
│   └── index.tsx           # Unified providers wrapper
├── stores/                 # Zustand stores
│   └── use-app-store.ts    # App store with persist middleware
└── types/                  # Shared TypeScript type definitions
    └── index.ts            # ApiResponse, PaginatedResponse, etc.
```

## Conventions

- **Package manager** - Always use `pnpm`
- **Imports** - Use the `@/*` path alias (maps to `src/*`)
- **Styling** - Tailwind CSS utility classes; use `cn()` from `@/lib/utils` for conditional classes
- **Components** - shadcn/ui as the base component library. Add new components via `pnpm dlx shadcn@latest add <component-name>`
- **State** - Zustand for client-side global state; TanStack Query for server/async state
- **Data fetching** - Wrap Axios calls in TanStack Query hooks (see `src/hooks/use-example.query.ts`)
- **Forms** - React Hook Form + Zod schemas from `@/lib/validations.ts`

## Environment Variables

Copy `.env.example` to `.env.local` and fill in the values:

```bash
cp .env.example .env.local
```

Client-side variables (prefixed with `NEXT_PUBLIC_`) and server-side variables are validated at runtime using Zod schemas defined in `src/lib/env.ts`.