Vite 5.x optimizeDeps: include vs exclude precedence unresolved

Answer First: Pre‑bundling Precedence

In Vite 5.x the optimizeDeps step still uses two lists: include (force pre‑bundle) and exclude (prevent pre‑bundle). The current implementation gives include higher priority – a module listed in both will be pre‑bundled. This is not officially documented and can differ between 5.0.x and 5.1.x releases.

Why This Matters

• Pre‑bundling a large module inflates the production bundle and can trigger runtime errors.
• When a module is needed only at runtime, you must guarantee it is excluded.

Reliable Configuration Pattern

1. Remove from include – keep only the exclude entry. Vite will honour the exclusion.
2. Use resolve.alias to redirect the import to a local stub that Vite will skip. Example:

   import path from 'path';
   export default {
     resolve: {
       alias: {
         'big-lib': path.resolve(__dirname, 'src/stubs/big-lib.js')
       }
     }
   };
   

3. When the above is not feasible, add a tiny plugin that runs after optimization and prunes the module from the graph:

   export default {
     name: 'prune-big-lib',
     enforce: 'post',
     configResolved(cfg) {
       cfg.optimizeDeps.preloadModules = cfg.optimizeDeps.preloadModules.filter(m => m !== 'big-lib');
     }
   };
   

Verification Steps

1. Run vite build --debug and look for the module under the optimizeDeps section. If it appears in the included list, include overrides exclude.
2. Inspect dist with a tool like source-map-explorer to confirm the module is omitted.
3. If the module still shows up, temporarily remove it from the include list and rebuild.
4. For a definitive check, add the custom plugin above and observe that the module disappears from the generated bundle.

Missing Detail Needed

What exact Vite minor version are you using (e.g., 5.0.3 vs 5.1.2)? Precedence can shift between releases, so knowing the patch level helps confirm the current rule.