Vue Proximity Prefetch

Features

• 🔍 Smart Detection: Detects when the user's mouse approaches navigation links
• ⚡ Automatic Prefetching: Preloads route components before the user clicks
• 📈 Enhanced UX: Reduces perceived loading times for smoother navigation
• 🔌 Simple Integration: Two easy ways to integrate - Vue component or Vite plugin
• 🔧 Highly Configurable: Customize threshold distance, prediction intervals, and more
• 🪶 Lightweight: Minimal overhead with intelligent throttling

Installation

1# npm
2npm install v-proximity-prefetch
3
4# yarn
5yarn add v-proximity-prefetch
6
7# pnpm
8pnpm add v-proximity-prefetch

Getting Started

There are two ways to use Vue Proximity Prefetch:

Method 1: Using the Vue Component and Plugin

This method gives you fine-grained control over which parts of your app use proximity prefetching.

1. Register the Plugin in your Vue app:

1// main.ts or main.js
2import { createApp } from 'vue'
3import { createRouter, createWebHistory } from 'vue-router'
4import App from './App.vue'
5import { ProximityPrefetchPlugin } from 'v-proximity-prefetch'
6
7const app = createApp(App)
8const router = createRouter({
9  history: createWebHistory(),
10  routes: [
11    // your routes...
12  ]
13})
14
15app.use(router)
16app.use(ProximityPrefetchPlugin) // register the plugin
17
18app.mount('#app')

2. Use the Component in your template:

1<!-- App.vue or any layout component -->
2<template>
3  <header>
4    <nav>
5      <router-link to="/">Home</router-link>
6      <router-link to="/about">About</router-link>
7      <router-link to="/contact">Contact</router-link>
8    </nav>
9  </header>
10
11  <main>
12    <!-- Wrap your router-view with ProximityPrefetch -->
13    <ProximityPrefetch :threshold="200" :prediction-interval="0">
14      <router-view />
15    </ProximityPrefetch>
16  </main>
17</template>
18
19<script setup>
20import { ProximityPrefetch } from 'v-proximity-prefetch'
21</script>

Method 2: Using the Vite Plugin Only

This method is simpler and doesn't require adding components to your app. Perfect for quick implementation.

1// vite.config.js or vite.config.ts
2import { defineConfig } from 'vite'
3import vue from '@vitejs/plugin-vue'
4import { viteProximityPrefetch } from 'v-proximity-prefetch'
5
6export default defineConfig({
7  plugins: [
8    vue(),
9    viteProximityPrefetch({
10      threshold: 200,
11      predictionInterval: 0,
12      maxPrefetch: 3,
13      automaticPrefetch: true // This enables automatic prefetching!
14    })
15  ]
16})

Configuration Options

Component Props

Prop	Type	Default	Description
threshold	number	200	Distance in pixels at which prefetching triggers
predictionInterval	number	0	Interval in ms for checking link proximity (0 means reactive to mouse movements)
debug	boolean	false	Enable debug logging

Vite Plugin Options

Option	Type	Default	Description
threshold	number	200	Distance in pixels at which prefetching triggers
predictionInterval	number	0	Interval in ms for checking link proximity
maxPrefetch	number	3	Maximum number of routes to prefetch at once
debug	boolean	false	Enable debug logging
automaticPrefetch	boolean	false	Enable automatic prefetching without the Vue component

Debug Mode

You can enable debug mode by setting the PPF_DEBUG environment variable:

1PPF_DEBUG=true npm run build

Or in the browser console:

1window.PPF_DEBUG = true

When to Use Each Method

• Component Method: More control, prefetches both Vue Router components and routes
• Vite Plugin Method: Simpler implementation, uses browser's standard prefetching

Demo

Check out the live demo to see the performance difference!

Browser Support

Vue Proximity Prefetch works in all modern browsers that support <link rel="prefetch">.

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

License

MIT

---

If you find this plugin useful, please ⭐ the GitHub repository and share it with other Vue developers!