Maaz Zindani

Loading the index…

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

Nuxt shows edits only after a manual browser refresh

ErrorSave a file and the browser stays the same until F5

Short answer

Nuxt runs Vite underneath, so Vite's HMR rules apply. Edits that appear only after a manual reload usually mean the file change was never seen (WSL2 or a shared folder), the import path differs in letter case from the file, or the module is in an import loop. Fix the one that matches.

  • Applies to Nuxt 4, Vite 7, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Save a file and watch the terminal that runs nuxt dev. If it prints an update line for the file, the change was seen and the problem is in the update chain. If nothing prints, the file watcher is the problem.

    npx nuxt dev
  2. 2Match what you see, then jump to its fix

    1. 1No terminal output at all after saving; the project sits on a Windows drive seen from WSL2 or on a VM shared folderThe file system does not report changes (WSL2 or a shared folder)Fix
    2. 2The terminal shows the change, but the browser does not updateAn import differs in letter case from the file nameFix
    3. 3Only some files fall back to a full reloadThe edited module is part of a circular importFix

What does the error look like?

  • Save a file and the browser stays the same until F5

Cause 1 of 3

The file system does not report changes (WSL2 or a shared folder)

1Check

Vite's troubleshooting guide says file changes may not be detected under WSL2, and the server.watch option documents polling for it. Nuxt passes its vite option straight through to Vite.

pwd

2Fix

Enable polling through Nuxt's vite option. It costs CPU, so moving the project to the Linux file system is the better fix.

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    server: { watch: { usePolling: true } },
  },
})

3Verify

Restart nuxt dev, save a file and see the update line.

npx nuxt dev

Confirmed by vite.dev

Did this fix it?

Cause 2 of 3

An import differs in letter case from the file name

1Check

The guide lists 'change detected but HMR not working' as an import casing problem, such as ./Foo.js for a file called foo.js.

git ls-files app components | grep -i "foo"

2Fix

Make the import path match the file name exactly.

git mv components/foo.vue components/Foo.vue

3Verify

Edit the component and check that the page updates.

npx nuxt dev

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

The edited module is part of a circular import

1Check

Vite falls back to a full reload when the update is in a circular dependency.

grep -rn "import" composables utils | head -50

2Fix

Move the shared code to a third file that both import, so the graph has no loop.

// utils/shared.ts holds what a.ts and b.ts both need

3Verify

Save one of the former loop files; the page updates without a reload.

npx nuxt dev

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Keep Nuxt projects on the Linux file system when using WSL2.
  • Run the build on Linux in CI to surface import-case mistakes.
  • Avoid files that import each other; shared code goes into its own module.

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

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

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