teatea-pension/.trellis/spec/frontend/index.md

Next.js Frontend Development Guidelines

Universal frontend development guidelines for Next.js full-stack applications with React + TypeScript + TailwindCSS.

Tech Stack

• Framework: Next.js 15, React 19
• Language: TypeScript (strict mode)
• Styling: TailwindCSS 4, Radix UI
• API: oRPC (OpenAPI RPC), React Query (TanStack Query)
• URL State: nuqs
• Auth: better-auth
• AI: Vercel AI SDK (@ai-sdk/react)

---

Documentation Files

File	Description	Priority
components.md	Server/Client components, semantic HTML, next/image	Must Read
authentication.md	better-auth client, session, protected routes	Must Read
orpc-usage.md	Type-safe API calls, React Query integration	Must Read
hooks.md	Query and mutation hook patterns	Reference
api-integration.md	oRPC client, real-time, AI streaming	Reference
state-management.md	URL state with nuqs, React Context patterns	Reference
directory-structure.md	Project structure and module conventions	Reference
type-safety.md	TypeScript guidelines, type inference, Zod	Reference
css-layout.md	CSS patterns, flexbox, responsive, touch	Reference
ai-sdk-integration.md	useChat hook, streaming, tool call handling	Reference
quality.md	Pre-commit checklist and code quality standards	Reference

---

Quick Navigation by Task

Before Starting Development

Task	Document
Understand project structure	directory-structure.md
Learn Server vs Client components	components.md
Set up authentication	authentication.md

During Development

Task	Document
Make type-safe API calls	orpc-usage.md
Create custom hooks	hooks.md
Manage application state	state-management.md
Build UI components	components.md
Ensure type safety	type-safety.md
Integrate AI features	ai-sdk-integration.md
Handle CSS & layout	css-layout.md

Before Committing

Task	Document
Run quality checklist	quality.md
Verify CSS in both envs	css-layout.md
Check type safety	type-safety.md

---

Core Rules Summary

Rule	Reference
Default to Server Components	components.md
Use <button> for clickable actions, not <div>	components.md
Always use next/image instead of <img>	components.md
Import types from backend, never redefine them	type-safety.md
No any types or @ts-expect-error in new code	type-safety.md
Use oRPC client for API calls (not raw fetch)	orpc-usage.md
Use oRPC generated query keys (not manual strings)	orpc-usage.md
Store shareable state in URL with nuqs	state-management.md
Use items-stretch on main flex containers	css-layout.md
Handle both tool call formats (streaming + history)	ai-sdk-integration.md
Always check session loading state before rendering	authentication.md

---

Architecture Overview

+--------------------------------------------------------------+
|                    Next.js Application                        |
|                                                               |
|  app/                          modules/                       |
|  ├── (marketing)/              ├── [feature]/                 |
|  │   └── [locale]/             │   ├── components/            |
|  └── (app)/                    │   ├── hooks/                 |
|      └── [routes]/             │   ├── context/               |
|                                │   └── lib/                   |
|                                ├── shared/                    |
|                                └── ui/                        |
+-------------------------------+------------------------------+
                                |
          oRPC (type-safe RPC)  |  React Query (cache)
                                |
+-------------------------------+------------------------------+
|                    API Layer (Server)                         |
|  +--------------+  +----------------+  +------------------+  |
|  |   oRPC       |  |   better-auth  |  |   AI SDK         |  |
|  |   Router     |  |   Sessions     |  |   Streaming      |  |
|  +--------------+  +----------------+  +------------------+  |
+--------------------------------------------------------------+

---

Getting Started

1. Read the Must-Read documents - Components, authentication, and oRPC usage
2. Set up your project structure - Follow directory-structure.md
3. Configure TypeScript paths - See type-safety.md
4. Set up API client - Use patterns from orpc-usage.md
5. Build components - Follow components.md and hooks.md
6. Before committing - Complete the quality.md checklist

---

Language: All documentation is written in English.