Maaz Zindani

Loading the index…

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

Vite reloads the page when it finds new dependencies and an end-to-end test fails

ErrorThe page reloads by itself a few seconds after the dev server starts

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

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

Fix it fast

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

    1. 1The 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. 2The reload follows a package that lives in the same repository and is symlinked into node_modulesA linked package is not plain ESMFix
    3. 3Odd behaviour right after switching branches or updating packagesThe cache is stale after a lockfile or config changeFix

What does the error look like?

  • The page reloads by itself a few seconds after the dev server starts
  • An end-to-end test fails once on a fresh checkout and passes on the second run
  • The 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-deps

2Fix

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 dev

Confirmed by vite.dev

Did this fix it?

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

Confirmed by vite.dev

Did this fix it?

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/.vite

2Fix

Force a fresh bundle, or delete the cache folder.

npx vite --force

3Verify

The first load after the forced start is stable.

npm run dev

Confirmed by vite.dev

Did this fix it?

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 fix

Next step

Want this handled for good?

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