Diagnose slow or overheating Next.js apps. Works in dev and production.
Steps
1. Check for compile loops
ls -lh /tmp/*.log 2>/dev/null
# If any log is >100MB, a hot reload loop is running
Look for repeated module resolution errors in the dev server output. Common culprit: geist/font/* imports breaking with Turbopack. Fix by switching to next/font/google:
// layout.tsx — replace geist package imports
import { Geist, Geist_Mono } from "next/font/google";
const GeistSans = Geist({ subsets: ["latin"], variable: "--font-geist-sans" });
const GeistMono = Geist_Mono({ subsets: ["latin"], variable: "--font-geist-mono" });
2. Check file watching scope
If the project reads files outside its own directory at runtime:
// lib/something.ts
const ROOT = path.join(process.cwd(), ".."); // watches the parent dir
Turbopack watches any directory referenced by runtime file reads. Edits to files in .. trigger full recompiles. Fix: scope reads to the project directory, or use turbopack: {} in next.config.ts to silence the warning while you plan a proper fix.
3. Check for uncached disk reads
grep -rn "fs.readFileSync\|fs.readdirSync" lib/ app/ src/ 2>/dev/null
Any function that reads files and is called from a server component runs on every request. Add a module-level cache:
let cache: ReturnType<typeof loadData> | null = null;
export function loadData() {
if (cache) return cache;
// ... read files ...
cache = result;
return cache;
}
4. Profile the bundle (production)
npx @next/bundle-analyzer
# or add to next.config.ts:
# bundleAnalyzer: { enabled: process.env.ANALYZE === 'true' }
Look for: large client components that could be server components, duplicate packages across chunks, packages that shouldn't be in the client bundle.
5. Find expensive server components
Server components re-render on every request in dev unless wrapped with cache(). Search for:
grep -rn "await fetch\|readFileSync\|prisma\.\|supabase\." app/ --include="*.tsx" --include="*.ts"
Any expensive call in a server component without import { cache } from 'react' wrapping it will run on every page load.
6. Report
State:
- Root cause (loop, file watching, uncached reads, bundle)
- Files changed and what changed
- Expected behavior after fix (idle CPU, hot reload time)