nextjs

Next.js

Invocation Protocol

When invoked directly as /nextjs, read this file first and apply the critical rules below before editing. Then read standards/nextjs/_INDEX.md and load only the additional refs/*.md entries whose file patterns or keywords match the task.

If both App Router and Pages Router signals appear, apply the Router Decision below before loading App Router-specific refs. For a Pages Router-only project, load refs/pages-router.md and treat App Router refs as informational unless the migration explicitly touches app/.

Router Decision

App Router is the default for new work. If the project uses pages/, treat App Router rules as informational and load refs/pages-router.md; do not apply app/ conventions, Server Components, or Server Actions to a Pages Router-only project.

P0 - Server & Client Components

• App Router uses React Server Components by default. Keep pages and layouts as Server Components unless they need hooks, browser APIs, or event handlers.
• Push 'use client' to interactive leaves such as buttons, forms, charts, and wrappers. Do not mark the tree root client-side.
• Compose Server Components through Client Component children; never import a Server Component into a Client Component.
• Server-to-Client props must be serializable: strings, numbers, booleans, plain objects, and arrays. Convert Date to strings and avoid functions, classes, Map, Set, and Symbol values except Server Actions marked 'use server'.
• Never pass secrets, raw ORM models, or full DB objects to the client. Use DTOs and server-only for sensitive modules.
• Avoid browser-only values (window, Date.now(), layout reads) in initial render; defer with a mounted state when needed.

Detail -> refs/server-components.md

P0 - Data Fetching & Access

• Fetch directly in async Server Components or call DB/service/DAL functions directly. Never fetch your own /api route from RSCs or server-side hooks.
• Pick cache behavior deliberately: cache: 'force-cache' for static data, next: { revalidate: N } for ISR, and cache: 'no-store' for request-time data.
• Parallelize independent work with Promise.all() and push slow fetches down behind <Suspense> instead of blocking the page root.
• Centralize secure data access in services/, lib/data.ts, or dal/ modules with import 'server-only'.
• Verify auth inside every DAL function, transform raw DB/API data into DTOs, and wrap shared reads with React cache() where render-cycle deduplication is needed.
• Use Server Actions or Route Handlers as bridges for Client Components; Client Components must not import DAL modules.