Disable VitePress Default Prefetch (Save Bandwidth)

Tested on: VitePress 1.6.3, 340 pages Symptom: Mobile users downloaded 15+ MB navigating one section. Server logs showed prefetch storm.

What VitePress prefetches

Default theme prefetches {base, head, payload} for links in viewport on hover/viewport.

Disable prefetch

.vitepress/config.mts:

export default defineConfig({
  themeConfig: {
    prefetchLinks: false
  }
})

Available since VitePress 1.0+. Confirm version:

npm ls vitepress

Selective prefetch (custom theme)

If you extend theme, remove prefetch plugin:

import DefaultTheme from 'vitepress/theme'

export default {
  ...DefaultTheme,
  setup() {
    // no DefaultTheme prefetch — disabled via config above
  }
}

Trade-off

Navigation feels ~80ms slower on fast connections — acceptable for 340-page docs.

Measure:

// DevTools → Network → disable cache → hover sidebar link
// Before: 200-400 KB prefetch
// After: 0 KB until click

CDN bill impact

Cloudflare bandwidth 22 GB/mo → 9 GB/mo (mostly prefetch elimination).

Verify

npm run docs:build && npm run docs:preview
# Network tab: hover internal links — no .md / .js prefetch requests

Re-enable for small sites

< 50 pages, keep default prefetchLinks: true for snappy UX.

Document the decision

Add to internal docs README:

## Performance note
prefetchLinks is false — large site (340+ pages).
Revisit if we split into smaller subsites.

Prevents next maintainer from "fixing" it back without testing bandwidth.

Verify production bandwidth

Cloudflare Analytics → compare egress week before/after disable:

Week	Egress
Prefetch on	22 GB
Prefetch off	9 GB

Result

Mobile data complaints dropped. INP unchanged. LCP improved slightly (less main-thread contention).