Vijay T - Technical Blog

Why Is My Next.js Compilation So Slow on macOS?

If you’ve ever stared at a sluggish terminal while running next dev on your Mac, you’re not alone. A slow development server can cripple productivity, but the good news is that most of the culprits are easy to identify and fix. Below is a step‑by‑step guide that covers the most common reasons for sluggish builds and how to resolve them.

---

🚀 Fast‑Track Wins (Apply These First)

Action	Why It Helps	How to Do It
Switch to Turbopack	Rust‑based bundler that’s dramatically faster for incremental builds.	bash\nnpm run dev -- --turbo\n<br>or add "dev": "next dev --turbo" to package.json.
Upgrade Node.js	Newer V8 and libuv improvements speed up compilation and module resolution.	Use nvm: <br>bash\nnvm install --lts\nnvm use --lts\n
Adopt pnpm	Efficient hard‑link based node_modules reduces disk I/O and install times.	bash\nnpm install -g pnpm\nrm -rf node_modules package-lock.json\npnpm install\n

---

⚙️ Next.js‑Specific Optimizations

1. Trim transpilePackages

transpilePackages forces Next.js to compile every file inside node_modules. Unless you have a specific ESM package that truly needs transpiling, remove it.

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Bad: transpilePackages: ['@mui/material', 'lodash', ...]
  // Good: only list packages that *must* be transpiled
  transpilePackages: ['some-esm-only-lib'],
};

module.exports = nextConfig;

2. Run a Bundle Analyzer

Seeing what ends up in your bundles helps you prune heavy dependencies.

// next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

/** @type {import('next').NextConfig} */
const nextConfig = {
  // …your other config
};

module.exports = withBundleAnalyzer(nextConfig);

ANALYZE=true npm run build   # opens a visual bundle map

3. Verify SWC Minification

Next.js ships with SWC (a Rust compiler) for fast minification. Make sure you haven’t unintentionally switched to a slower tool like Terser.

// next.config.js
module.exports = {
  swcMinify: true,   // explicit but already the default
};

---

🖥️ macOS & System‑Level Tweaks

Fix	What It Does	How to Apply
Disable Antivirus / Security Software (temporarily)	Stops real‑time file scanning that blocks fast HMR.	Pause your security suite, test speed, then add an exclusion for your project folder, node_modules, and .next.
Exclude Project from Spotlight Indexing	Prevents Spotlight from constantly reading your dev files.	bash\nsudo mdutil -i off /path/to/project\nsudo mdutil -i off /path/to/project/node_modules\nsudo mdutil -i off /path/to/project/.next\n
Tame Your IDE	Heavy extensions and frequent file scanning consume CPU cycles.	VS Code: <br>json\n// settings.json\n\"files.exclude\": { \"**/node_modules\": true, \"**/.next\": true },\n\"search.exclude\": { \"**/node_modules\": true, \"**/.next\": true }\n<br>Disable unused extensions (linters, AI assistants, etc.).

---

🧠 Structured Debug Workflow

1. Create a Fresh Baseline

   npx create-next-app@latest test-app
   cd test-app
   npm run dev     # or npm run dev -- --turbo
   

   • If this is fast, the issue lives in your project’s code or dependencies.
   • If it’s still slow, the problem is likely system‑wide.

2. Profile the Dev Server

   NODE_OPTIONS='--inspect' next dev
   

   Open chrome://inspect in Chrome, connect to the Node process, and review CPU profiles.

3. Check Hardware

   • RAM: ≤ 8 GB → frequent swapping → upgrade to ≥ 16 GB.
   • Drive: HDD drastically slows file watching. Use an SSD (or the built‑in Apple Silicon storage).
   • CPU: Apple Silicon (M1/M2/M3) offers huge gains over Intel for compilation tasks.

---

✅ Quick‑Start Checklist

• [ ] Run next dev -- --turbo
• [ ] Update to the latest Node.js LTS via nvm
• [ ] Switch your project to pnpm
• [ ] Remove unnecessary entries from transpilePackages
• [ ] Run ANALYZE=true npm run build and prune heavy dependencies
• [ ] Temporarily disable security software or add exclusions
• [ ] Exclude project folders from Spotlight indexing
• [ ] Optimize your IDE settings (exclude node_modules & .next)

---

By applying these optimizations step‑by‑step, you should see a noticeable reduction in build times and a smoother development experience on your Mac. Happy coding!