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
<Suspense> 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
