126 lines
7.3 KiB
Markdown
126 lines
7.3 KiB
Markdown
# 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](./components.md) | Server/Client components, semantic HTML, next/image | **Must Read** |
|
|
| [authentication.md](./authentication.md) | better-auth client, session, protected routes | **Must Read** |
|
|
| [orpc-usage.md](./orpc-usage.md) | Type-safe API calls, React Query integration | **Must Read** |
|
|
| [hooks.md](./hooks.md) | Query and mutation hook patterns | Reference |
|
|
| [api-integration.md](./api-integration.md) | oRPC client, real-time, AI streaming | Reference |
|
|
| [state-management.md](./state-management.md) | URL state with nuqs, React Context patterns | Reference |
|
|
| [directory-structure.md](./directory-structure.md) | Project structure and module conventions | Reference |
|
|
| [type-safety.md](./type-safety.md) | TypeScript guidelines, type inference, Zod | Reference |
|
|
| [css-layout.md](./css-layout.md) | CSS patterns, flexbox, responsive, touch | Reference |
|
|
| [ai-sdk-integration.md](./ai-sdk-integration.md) | useChat hook, streaming, tool call handling | Reference |
|
|
| [quality.md](./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](./directory-structure.md) |
|
|
| Learn Server vs Client components | [components.md](./components.md) |
|
|
| Set up authentication | [authentication.md](./authentication.md) |
|
|
|
|
### During Development
|
|
|
|
| Task | Document |
|
|
| --------------------------- | -------------------------------------------------- |
|
|
| Make type-safe API calls | [orpc-usage.md](./orpc-usage.md) |
|
|
| Create custom hooks | [hooks.md](./hooks.md) |
|
|
| Manage application state | [state-management.md](./state-management.md) |
|
|
| Build UI components | [components.md](./components.md) |
|
|
| Ensure type safety | [type-safety.md](./type-safety.md) |
|
|
| Integrate AI features | [ai-sdk-integration.md](./ai-sdk-integration.md) |
|
|
| Handle CSS & layout | [css-layout.md](./css-layout.md) |
|
|
|
|
### Before Committing
|
|
|
|
| Task | Document |
|
|
| ----------------------- | -------------------------------- |
|
|
| Run quality checklist | [quality.md](./quality.md) |
|
|
| Verify CSS in both envs | [css-layout.md](./css-layout.md) |
|
|
| Check type safety | [type-safety.md](./type-safety.md) |
|
|
|
|
---
|
|
|
|
## Core Rules Summary
|
|
|
|
| Rule | Reference |
|
|
| ------------------------------------------------------------ | -------------------------------------------------- |
|
|
| **Default to Server Components** | [components.md](./components.md) |
|
|
| **Use `<button>` for clickable actions, not `<div>`** | [components.md](./components.md) |
|
|
| **Always use `next/image` instead of `<img>`** | [components.md](./components.md) |
|
|
| **Import types from backend, never redefine them** | [type-safety.md](./type-safety.md) |
|
|
| **No `any` types or `@ts-expect-error` in new code** | [type-safety.md](./type-safety.md) |
|
|
| **Use oRPC client for API calls (not raw fetch)** | [orpc-usage.md](./orpc-usage.md) |
|
|
| **Use oRPC generated query keys (not manual strings)** | [orpc-usage.md](./orpc-usage.md) |
|
|
| **Store shareable state in URL with nuqs** | [state-management.md](./state-management.md) |
|
|
| **Use `items-stretch` on main flex containers** | [css-layout.md](./css-layout.md) |
|
|
| **Handle both tool call formats (streaming + history)** | [ai-sdk-integration.md](./ai-sdk-integration.md) |
|
|
| **Always check session loading state before rendering** | [authentication.md](./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](./directory-structure.md)
|
|
3. **Configure TypeScript paths** - See [type-safety.md](./type-safety.md)
|
|
4. **Set up API client** - Use patterns from [orpc-usage.md](./orpc-usage.md)
|
|
5. **Build components** - Follow [components.md](./components.md) and [hooks.md](./hooks.md)
|
|
6. **Before committing** - Complete the [quality.md](./quality.md) checklist
|
|
|
|
---
|
|
|
|
**Language**: All documentation is written in **English**.
|