next dev starts but the page hangs on compiling for minutes
npm run dev starts, but the browser tab loads for minutesShort 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.
Fix it fast
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 info2Match what you see, then jump to its fix
- 1
node -v prints a version below 20.9Node.js is older than the minimumFix - 2
The working directory starts with /mnt/cThe project sits on the Windows disk while you run it inside WSLFix - 3
Disk and security-process CPU stay busy during compilationAntivirus or Gatekeeper scans every file the compiler readsFix - 4
Edits 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
The 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
Every start is slow, and tailwind.config.js has a broad content globThe Tailwind content setting scans node_modules or a huge folderFix
- 1
What does the error look like?
npm run dev starts, but the browser tab loads for minutesFast 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 -v2Fix
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 install3Verify
Start the dev server again.
npm run devConfirmed by nextjs.org
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.
pwd2Fix
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 install3Verify
Run the dev server and edit a file; the change should appear in seconds.
npm run devConfirmed by nextjs.org
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 > Exclusions2Fix
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-terminal3Verify
Restart the terminal, run next dev and compare compile time.
npm run devConfirmed by nextjs.org
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 volumes2Fix
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 dev3Verify
Edit a component and time the refresh.
# the edit shows in the browser in about a secondConfirmed by nextjs.org
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/null2Fix
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 devConfirmed by nextjs.org
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.js2Fix
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 devConfirmed by nextjs.org
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
Web apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fix