Expose HMR retry limit in Vite config vs. keeping it hard‑coded

Answer the question first

Vite’s Hot Module Replacement (HMR) client currently retries a failed update up to three times before falling back to a full page reload. Exposing this limit as a configurable option would give teams control over retry aggressiveness, but it also introduces risks of duplicate writes, inconsistent behavior across environments, and potential misuse. A simple numeric option strikes a balance between flexibility and safety, while keeping the default of three attempts for most users.

Confirmed facts

• The hard‑coded limit lives in src/node/server/hmr.ts and is set to maxRetries = 3 with a 1‑second pause between attempts.
• Increasing the retry count can lead to the same patch being applied multiple times, which may corrupt module state if the update contains non‑idempotent side effects.
• Lowering the count reduces latency to a full reload but may hide transient network glitches that a higher limit would recover from.
• Adding a runtime configuration requires the HMR client to read the value on each connection; the overhead is negligible for typical projects.

Likely explanation

Teams that experience flaky networks often want faster recovery, while others value the safety of a full reload when an update fails repeatedly. A numeric option allows quick tuning without exposing complex back‑off logic that could be misconfigured. If more sophisticated control is needed, a dedicated plugin could still provide custom retry strategies.

Practical steps for a project that wants a custom limit

1. Open vite.config.ts (or .js) and add a server.hmr.retry field:

   export default defineConfig({
     server: {
       hmr: {
         retry: 5 // retry up to 5 times instead of the default 3
       }
     }
   });
   

2. Restart the dev server. The console will log the configured retry count on each HMR connection.

3. To verify duplicate writes, instrument a module with a console.log in its exported function and observe how many times it runs when a network timeout occurs.

4. Use browser dev‑tools throttling or a network simulation tool (e.g., tc) to emulate flaky conditions and compare the experience with the default and custom limits.

Potential pitfalls

• Very high retry counts can mask real errors, leading to silent failures.
• Different team members using different limits may see divergent behavior, complicating debugging.
• Future Vite releases may alter the retry logic; a public API must be version‑guarded to avoid breaking existing projects.

Recommendation

Expose a simple numeric option (server.hmr.retry) with a clear default of 3. Document the risks of duplicate writes and advise keeping the value low for modules that perform side effects. If a team requires more granular control, they can implement a custom HMR plugin instead of relying on the built‑in setting.

Missing diagnostic detail

Do you have modules that perform non‑idempotent side effects (e.g., network requests or state mutations) that could be duplicated on retry? This information could influence whether the default should remain stricter or a higher limit is acceptable.