Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

next dev starts but the page hangs on compiling for minutes

Errornpm run dev starts, but the browser tab loads for minutes

Short answer

A hung next dev is nearly always the machine or the import graph, not a Next.js bug. Check the Node.js version, then where the project lives (WSL on /mnt/c, Docker bind mounts), then antivirus scanning, then huge icon or barrel imports and a Tailwind content glob that reaches node_modules.

  • Applies to Next.js 16, Node.js 22, Node.js 24, Turbopack
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the Node.js and Next.js versions Next.js sees. The installation guide gives the minimum Node.js as 20.9.

    node -v
    npx next info
  2. 2Match what you see, then jump to its fix

    1. 1node -v prints a version below 20.9Node.js is older than the minimumFix
    2. 2The working directory starts with /mnt/cThe project sits on the Windows disk while you run it inside WSLFix
    3. 3Disk and security-process CPU stay busy during compilationAntivirus or Gatekeeper scans every file the compiler readsFix
    4. 4Edits take seconds to minutes to appear, but the same app is fast outside Dockernext dev runs in Docker on a mounted project folder (Mac or Windows)Fix
    5. 5The first compile of a route is slow, and the project imports from an icon library or a barrel fileOne import pulls in thousands of modulesFix
    6. 6Every start is slow, and tailwind.config.js has a broad content globThe Tailwind content setting scans node_modules or a huge folderFix

What does the error look like?

  • npm run dev starts, but the browser tab loads for minutes
  • Fast Refresh takes seconds or minutes to show an edit

Cause 1 of 6

Node.js is older than the minimum

1Check

The installation guide lists 20.9 as the minimum Node.js version for current Next.js.

node -v

2Fix

Install a supported Node.js version (22 or 24 are current) with your version manager, then reinstall dependencies.

nvm install 22
nvm use 22
rm -rf node_modules && npm install

3Verify

Start the dev server again.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 6

The project sits on the Windows disk while you run it inside WSL

1Check

The local development guide says that under WSL 2 the project must live in the Linux filesystem, because on a Windows drive performance suffers and file updates may not show up.

pwd

2Fix

Move the project into your Linux home directory and run it from there.

mkdir -p ~/projects
cp -r /mnt/c/Users/you/my-app ~/projects/my-app
cd ~/projects/my-app && npm install

3Verify

Run the dev server and edit a file; the change should appear in seconds.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 6

Antivirus or Gatekeeper scans every file the compiler reads

1Check

The guide names antivirus software as a common slowdown, on Windows and on macOS.

# Windows: Windows Security > Virus & threat protection > Manage settings > Exclusions

2Fix

On Windows, add the project folder as an exclusion in Microsoft Defender, or use a Dev Drive. On macOS, enable developer mode for your terminal, then make sure the terminal is listed in Privacy & Security > Developer Tools and restart it.

sudo spctl developer-mode enable-terminal

3Verify

Restart the terminal, run next dev and compare compile time.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 4 of 6

next dev runs in Docker on a mounted project folder (Mac or Windows)

1Check

The guide explains that file events can be delayed or lost across Docker Desktop's host-to-VM share, which makes Fast Refresh slow.

docker compose config | grep -A3 volumes

2Fix

Run next dev directly on the host during development and keep Docker for production builds. If you must use Docker, try synchronized file shares. The guide warns against polling as more than a last resort.

npm run dev

3Verify

Edit a component and time the refresh.

# the edit shows in the browser in about a second

Confirmed by nextjs.org

Did this fix it?

Cause 5 of 6

One import pulls in thousands of modules

1Check

The guide says libraries such as react-icons or @phosphor-icons/react can import thousands of icons, and barrel files force the compiler to parse everything they re-export.

grep -rn "from 'react-icons\|from '@phosphor-icons/react'" app components src 2>/dev/null

2Fix

Import only the files you need, and use one icon set. If you use webpack (next dev --webpack), list barrel-style packages in optimizePackageImports. The guide says Turbopack does not need it.

// next.config.js
module.exports = {
  experimental: {
    optimizePackageImports: ['package-name'],
  },
}

3Verify

Restart the dev server and open the slow route again.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 6 of 6

The Tailwind content setting scans node_modules or a huge folder

1Check

The guide calls a content array that includes node_modules or other large directories a common mistake, and says Tailwind CSS 3.4.8 and newer warns about such settings.

grep -n -A6 "content" tailwind.config.js

2Fix

Point content at your source folders only.

module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
}

3Verify

Restart the dev server and watch for a Tailwind warning in the terminal.

npm run dev

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Keep projects on the native filesystem of the OS that runs them.
  • Use named imports from specific files for icon libraries.
  • Keep next up to date, since the guide says each release brings performance work.
  • Run next dev on the host, not in Docker, while you develop.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.