Maaz Zindani

Loading the index…

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

next dev is very slow to compile and refresh

ErrorThe first visit to every route takes many seconds in development

Short 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.

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

Fix it fast

  1. 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.bin
  2. 2Match what you see, then jump to its fix

    1. 1Slowness on Windows or macOS only, and disk or antivirus processes are busy.Antivirus scans every file Next.js touchesFix
    2. 2Fast 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. 3The 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. 4Edits 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

What does the error look like?

  • The first visit to every route takes many seconds in development
  • Fast 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 ExclusionPath

2Fix

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 it

3Verify

Restart next dev and compare the first-visit time.

npm run dev

Confirmed by nextjs.org

Did this fix it?

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 ps

2Fix

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 dev

3Verify

Save a file and time how long the browser takes to show it.

npm run dev

Confirmed by nextjs.org

Did this fix it?

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 | head

2Fix

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 dev

Confirmed by nextjs.org

Did this fix it?

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 dev

Confirmed by nextjs.org

Did this fix it?

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

Next step

Want this handled for good?

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