next dev is very slow to compile and refresh
The first visit to every route takes many seconds in developmentShort answer
next dev compiles each route on first visit, so some delay is normal. Long delays usually come from antivirus scanning the project, a Docker bind mount on macOS or Windows, icon or barrel-file imports that pull in thousands of modules, a Tailwind content glob that reaches node_modules, or a custom webpack setup.
Fix it fast
1Find out which cause you have
Turn on detailed fetch logging and generate a Turbopack trace, so you can see whether time goes to compiling or to your own data fetching.
npm run dev -- --internal-trace # stop the server, then: npx next internal trace .next-profiles/trace-turbopack.bin2Match what you see, then jump to its fix
- 1
Slowness on Windows or macOS only, and disk or antivirus processes are busy.Antivirus scans every file Next.js touchesFix - 2
Fast Refresh is delayed far more than the compile times in the trace.The project is mounted into Docker Desktop, or sits on a Windows drive in WSL 2Fix - 3
The trace shows very many modules for a small page; the import is from a package root such as react-icons or an index.ts that re-exports everything.Icon libraries and barrel files pull in thousands of modulesFix - 4
Edits to CSS or any file are slow; tailwind.config.js has a content glob that starts at a parent folder, or next.config has a webpack function.Tailwind scans too many files, or a custom webpack config is slowFix
- 1
What does the error look like?
The first visit to every route takes many seconds in developmentFast Refresh takes seconds or minutes after saving a file
Cause 1 of 4
Antivirus scans every file Next.js touches
1Check
The Next.js guide names antivirus software as a common cause. On Windows, check whether the project folder is excluded in Microsoft Defender.
Get-MpPreference | Select-Object -ExpandProperty ExclusionPath2Fix
On Windows add the project folder to the Defender exclusions, or use a Dev Drive. On macOS enable developer mode for your terminal as the guide describes.
sudo spctl developer-mode enable-terminal
# then: System Settings > Privacy & Security > Developer Tools, enable your terminal, restart it3Verify
Restart next dev and compare the first-visit time.
npm run devConfirmed by nextjs.org
Cause 2 of 4
The project is mounted into Docker Desktop, or sits on a Windows drive in WSL 2
1Check
Project files shared from the macOS or Windows host through Docker Desktop can delay file-watching events. In WSL 2 a project under /mnt/c has the same problem.
pwd && docker compose ps2Fix
Run next dev directly on the host, or keep the project inside the Linux filesystem (for WSL 2, a path like /home/<user>/project). Avoid watchOptions.pollIntervalMs unless nothing else works, because polling raises CPU and I/O use.
cp -r /mnt/c/work/my-app ~/my-app && cd ~/my-app && npm run dev3Verify
Save a file and time how long the browser takes to show it.
npm run devConfirmed by nextjs.org
Cause 3 of 4
Icon libraries and barrel files pull in thousands of modules
1Check
Libraries like @material-ui/icons, @phosphor-icons/react and react-icons can import thousands of icons even when you use a few. Barrel files make the compiler parse each re-export.
grep -rnE "from '(react-icons|@mui/icons-material|@phosphor-icons/react)'" app src components 2>/dev/null | head2Fix
Import the single file you need, or list the package under optimizePackageImports when you are on webpack. Turbopack does this analysis on its own.
// next.config.js (webpack only)
module.exports = {
experimental: {
optimizePackageImports: ['package-name'],
},
}3Verify
Compare the first-visit time and the trace after the change.
npm run devConfirmed by nextjs.org
Cause 4 of 4
Tailwind scans too many files, or a custom webpack config is slow
1Check
A content array that includes node_modules or large folders makes Tailwind scan them. Tailwind CSS 3.4.8 or newer warns about such settings. Custom webpack settings can also slow compilation, and on Next.js 16 Turbopack is the default bundler.
grep -n "content" -A6 tailwind.config.js; grep -n "webpack" next.config.*2Fix
Narrow the content globs to your source folders, and drop development-only webpack additions or replace them with Turbopack loader configuration.
// tailwind.config.js
module.exports = {
content: ['./src/**/*.{js,ts,jsx,tsx}'],
}3Verify
Restart next dev and edit a component.
npm run devConfirmed by nextjs.org
How do I stop it coming back?
- Stay on a current Next.js release: the guide says each release often includes dev performance work, and Turbopack is the default in dev.
- Import icons from one set and from specific files, not from a package root that re-exports all of them.
- Develop on the host, not in a bind-mounted container, and use containers for production builds.
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
next dev starts but the page hangs on compiling for minutes
Fast Refresh takes seconds or minutes to show an edit
A hung next dev is nearly always the machine or the import graph, not a Next.js bug.
6 causes, each with a fixWeb 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 fix