Next.js Architecture Guide
Project structure, routing patterns, data fetching strategies, and best practices for building production-grade Next.js applications with the App Router.
Project Structure
We follow a feature-oriented structure that scales well from small projects to large applications. The key principle is colocation: keep related code together.
app/
(auth)/ -- Route group for auth pages
(dashboard)/ -- Route group for authenticated pages
api/ -- API route handlers
components/
ui/ -- Reusable design system components
[feature]/ -- Feature-specific components
lib/
actions/ -- Server actions
queries/ -- Database query functions
validations/ -- Zod schemas
hooks/ -- Custom React hooks
types/ -- TypeScript type definitions
Server vs Client Components
Server Components (default)
- Data fetching
- Database access
- Backend logic
- Static content
- SEO-critical pages
Client Components ("use client")
- Interactivity (onClick, onChange)
- Browser APIs (localStorage)
- State management (useState)
- Effects (useEffect)
- Third-party client libraries
Data Fetching Patterns
Fetch data directly in Server Components using async/await. No useEffect, no loading states to manage on the client.
Use server actions for mutations (forms, button clicks). They run on the server and can revalidate caches.
Use SWR for client-side data that needs real-time sync between components. Ideal for dashboards and collaborative UIs.
Use app/api/ routes for webhook endpoints, third-party integrations, and when you need fine-grained HTTP control.
Performance Checklist
- Use Server Components by default, add "use client" only when needed
- Implement loading.tsx and error.tsx for every route segment
- Use next/image for automatic optimization and lazy loading
- Implement parallel data fetching with Promise.all in layouts
- Use generateStaticParams for static pages that benefit from ISR
- Keep client-side JavaScript minimal with dynamic imports
Need help architecting a Next.js application? Get in touch and we will help design the right structure for your project.