nextjs-architecture

Next.js Architecture

Treat the App Router as the default. Only use the Pages Router if the project is already on it.

Non-negotiable rules

• Prefer Server Components by default; mark "use client" only when necessary.
• Do not import server modules into Client Components.
• Validate inputs at the edge (route handlers, Server Actions) with schemas.
• Authorization always on the server; never trust only the UI.
• Caching and revalidation are explicit decisions, not accidents.

Organization

app/                 # rotas, layouts, loading, error
features/<domínio>/  # UI, hooks, schemas, services do domínio
components/ui/       # primitivos reutilizáveis
lib/                 # auth, db, env, utils

• Place data fetching close to the route that needs the data.
• Extract domain logic into features/, not into generic “utils”.
• Keep layouts thin; heavy logic stays in modules/services.

Server vs Client

Use Client Components only for:

• interactive state and event handlers
• browser APIs
• libs that require the DOM

Keep on the server:

• secrets, DB, auth
• aggregations and permissions
• SEO-critical content

Pattern: server fetch → typed props → minimal client island.

Data and caching

• Consciously choose between static, dynamic and streaming.
• Use revalidate / tags / updateTag in a named and documented way.
• Avoid force-dynamic globally without reason.
• Deduplicate fetches; do not fire the same query in a cascade of components.
• Prefer Server Actions for co-located mutations; route handlers for public APIs/webhooks.

Route handlers and middleware

• Handlers: clear contracts, correct HTTP statuses, typed errors.
• Middleware: lightweight auth gate, redirects, headers; do not do heavy DB there.
• Protect sensitive routes on the server even with middleware.

Anti-patterns

• "use client" in the root layout without need
• Fetching data on the client just because “it is easier”
• Passing non-serializable objects from the server to the client
• Mixing business logic into page JSX
• Stale cache without invalidation after mutation

Integration with other skills

• i18n (locale in the App Router): i18n-frontend
• Server Actions: nextjs-server-actions

Completion criteria

• Correct and auditable server/client boundaries
• Routes organized by feature/domain
• Mutations validated and authorized on the server
• Explicit cache/revalidate strategy
• No leaking of secrets into the client bundle