Before writing Next.js code:
Read docs/agent/architecture/nextjs-critical-fixes.md for full patterns
Check existing components in apps/frontend/components/ for examples
Critical Rules (always apply):
Waterfalls
Use Promise.all() for independent fetches
Wrap slow data in boundaries
Defer await into branches where needed
Bundle Size
NO barrel imports: import X from 'lucide-react' ❌
YES direct imports: import X from 'lucide-react/dist/esm/icons/x' ✅
Use next/dynamic for heavy components (editors, charts, PDF viewers)
Defer analytics with ssr: false
Server Actions
ALWAYS check auth INSIDE the action, not just middleware
Verify resource ownership before mutations
Production Build
Users run npm run build && npm run start, NOT npm run dev
Docker must use standalone output, not dev mode
Quick Check Before PR:
[ ] No sequential awaits for independent data
[ ] Icons imported directly
[ ] Heavy components use next/dynamic
[ ] Server Actions have auth inside
[ ] Suspense around slow fetches