teatea-pension/.trellis/spec

Next.js Full-Stack Development Guidelines

Universal development guidelines for production Next.js applications with oRPC API layer and PostgreSQL.

Structure

Frontend

React 19 + Next.js 15 App Router frontend development patterns:

• Directory Structure
• Components
• State Management
• Hooks
• API Integration
• oRPC Usage
• Authentication
• AI SDK Integration
• CSS & Layout
• Type Safety
• Quality Checklist

Backend

oRPC + Drizzle ORM backend development patterns:

• Directory Structure
• oRPC Usage
• Authentication
• Database
• AI SDK Integration
• Logging
• Performance
• Type Safety
• Quality Checklist

Shared

Cross-cutting concerns:

• Dependencies
• Code Quality
• TypeScript Conventions

Guides

Development thinking guides:

• Pre-Implementation Checklist
• Cross-Layer Thinking Guide

Common Issues / Pitfalls

Common issues and solutions:

• PostgreSQL JSON vs JSONB
• WebKit Tap Highlight
• Sentry & next-intl Conflict
• Turbopack vs Webpack Flexbox

Tech Stack

• Frontend: Next.js 15, React 19, TailwindCSS 4, Radix UI, React Query
• Backend: oRPC, Drizzle ORM, PostgreSQL, better-auth
• AI: Vercel AI SDK (multi-provider)
• Real-time: Ably / WebSocket / SSE
• Build: Turborepo + pnpm (monorepo)
• Monitoring: Sentry + OpenTelemetry

Usage

These guidelines can be used as:

1. New Project Template - Copy the entire structure for new Next.js projects
2. Reference Documentation - Consult specific guides when implementing features
3. Code Review Checklist - Verify implementations against established patterns
4. Onboarding Material - Help new developers understand project conventions