name: nextjs-performance description: | Next.js critical performance fixes. Prevents async waterfalls, reduces bundle size, secures Server Actions, and ensures correct production builds. Use when writing React components, data fetching, Server Actions, or optimizing bundle size.

Next.js Performance

Before Writing Code

1. Read docs/agent/architecture/nextjs-critical-fixes.md for full patterns
2. Check existing components in apps/frontend/components/

Critical Rules

Waterfalls

• Use Promise.all() for independent fetches
• Wrap slow data in <Suspense> boundaries
• Defer await into branches where needed

// WRONG
const resumes = await fetchResumes();
const jobs = await fetchJobs();

// RIGHT
const [resumes, jobs] = await Promise.all([fetchResumes(), fetchJobs()]);

Bundle Size

• NO barrel imports: import X from 'lucide-react' is WRONG
• YES direct imports: import X from 'lucide-react/dist/esm/icons/x'
• Use next/dynamic for heavy components (editors, charts, PDF)
• Defer analytics with ssr: false

import dynamic from 'next/dynamic';
const HeavyEditor = dynamic(() => import('./HeavyEditor'), { ssr: false });

Server Actions

• ALWAYS check auth INSIDE the action, not just middleware
• Verify resource ownership before mutations

Production Build

• Run npm run build && npm run start, NOT npm run dev
• Docker must use standalone output

Pre-PR Checklist

[ ] No sequential awaits for independent data
[ ] Icons imported directly (not barrel)
[ ] Heavy components use next/dynamic
[ ] Server Actions have auth inside
[ ] Suspense around slow fetches