Vite reloads the page when it finds new dependencies and an end-to-end test fails
The page reloads by itself a few seconds after the dev server startsShort answer
Vite pre-bundles dependencies it finds at startup. An import it only discovers later, after a plugin transform or a lazy route, forces a second bundling run and a page reload in the middle of your test. List those packages in optimizeDeps.include so they are bundled before the first request.
Fix it fast
1Find out which cause you have
Start the dev server from a clean cache and watch the terminal while you open the app. A message about optimizing dependencies during the first visit means a late discovery.
npx vite --force2Match what you see, then jump to its fix
- 1
The reload happens when you open a route or component that imports a package the entry never touchedA dependency is found only after the first page loadsFix - 2
The reload follows a package that lives in the same repository and is symlinked into node_modulesA linked package is not plain ESMFix - 3
Odd behaviour right after switching branches or updating packagesThe cache is stale after a lockfile or config changeFix
- 1
What does the error look like?
The page reloads by itself a few seconds after the dev server startsAn end-to-end test fails once on a fresh checkout and passes on the second runThe terminal says new dependencies were optimized and the page is reloading
Cause 1 of 3
A dependency is found only after the first page loads
1Check
After startup, Vite re-runs bundling and reloads the page if needed when it meets an import that is not in the cache. This includes imports that only exist after a plugin transforms a file.
npx vite --debug optimize-deps2Fix
Add the packages named in the log to optimizeDeps.include, so they are bundled at startup.
// vite.config.js
export default defineConfig({
optimizeDeps: {
include: ['vuetify/components', 'some-lazy-package'],
},
})3Verify
Delete the cache once, start the server and run the test twice.
rm -rf node_modules/.vite
npm run devConfirmed by vite.dev
Cause 2 of 3
A linked package is not plain ESM
1Check
Vite treats a linked dependency as source code and does not bundle it. That needs the package to be exported as ESM.
ls -l node_modules | grep -- '->'2Fix
If the linked package is not ESM, add it to optimizeDeps.include. After changing it, restart with --force.
export default defineConfig({
optimizeDeps: { include: ['linked-dep'] },
})3Verify
Restart with a fresh cache and check that no reload appears.
npx vite --forceConfirmed by vite.dev
Cause 3 of 3
The cache is stale after a lockfile or config change
1Check
Vite re-runs pre-bundling when the lockfile, the patches folder, relevant config fields or NODE_ENV change. The cache lives in node_modules/.vite.
ls node_modules/.vite2Fix
Force a fresh bundle, or delete the cache folder.
npx vite --force3Verify
The first load after the forced start is stable.
npm run devConfirmed by vite.dev
How do I stop it coming back?
- In the test pipeline, start the dev server, open the app once to warm it, then run the tests; or test a production build served by vite preview.
- Keep optimizeDeps.include in the repository so every machine bundles the same set.
- Commit the lockfile so cache invalidation is predictable.
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 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
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fix