nextjs15-performance

Before writing Next.js code

1. Read

   docs/agent/architecture/nextjs-critical-fixes.md

   for full patterns
2. 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