EN | FR
vite-plugin-preload-assets is a Vite plugin designed to improve performance by automatically injecting <link rel="preload"> and <link rel="preconnect"> tags for critical resources (images, fonts, JS, and CSS) at build time.
- 📷 Automatically preloads images marked with
data-preload - 🌗 Handles dark mode variants (when using browserux-theme-switcher) and preloads them as well (e.g.
logo-dark.png) - 🔤 Preloads fonts via configuration (
fontsToPreload) - 🧠 Preloads critical JS/CSS files by matching configured names dynamically in the build output
- 🌐 Automatically injects
<link rel="preconnect">tags for Google Fonts (fonts.googleapis.com,fonts.gstatic.com) - 🚀 Optimizes initial load performance with zero manual effort
- 🧼 No manual HTML changes required
npm install vite-plugin-preload-assets --save-devIn the vite.config.ts, vite.config.js, or vite.config.mjs file:
import preloadAssetsPlugin from 'vite-plugin-preload-assets'
export default {
plugins: [
preloadAssetsPlugin({
preloadGoogleFonts: true,
fontsToPreload: [
{
href: '/fonts/Inter.woff2',
type: 'font/woff2',
crossorigin: true
}
],
criticalJs: ['main'],
criticalCss: ['main']
})
]
}Simply add the data-preload attribute to an image in your HTML:
<img src="/img/logo.png" data-preload width="100" height="100" alt="Logo">The plugin will automatically inject:
<link rel="preload" href="/img/logo.png" as="image">If your image also supports dark mode and is used with the browserux-theme-switcher, you can add the has-dark class:
<img src="/img/logo.png" class="has-dark" data-preload alt="Logo">This will inject both versions:
<link rel="preload" href="/img/logo.png" as="image">
<link rel="preload" href="/img/logo-dark.png" as="image">This ensures both light and dark versions are loaded early and switch instantly on theme change.
Explicitly preload images that are not in index.html (e.g. used in React components):
imagesToPreload: [
'/img/logo.png',
'/img/hero.jpg'
]This will generate:
<link rel="preload" href="/img/logo.png" as="image">
<link rel="preload" href="/img/hero.jpg" as="image">List of fonts to preload manually.
fontsToPreload: [
{
href: '/fonts/Inter.woff2', // URL (relative or absolute)
type: 'font/woff2', // MIME type (default : 'font/woff2')
crossorigin: true // add the `crossorigin` attribute
},
{
href: 'https://fonts.googleapis.com/css2?family=Dosis:wght@200..800&display=swap',
as: 'style', // Override preload type (default: 'font')
crossorigin: true
}
]- You can override the
asattribute ('font'by default) to support custom cases like Google Fonts CSS. - If you're preloading a CSS file from Google Fonts, use
as: 'style'.
If
ais not set to'font', the plugin will automatically skip thetypeattribute to avoid preload warnings.
Automatically injects the preconnect tags needed to optimize the loading of Google Fonts:
preloadGoogleFonts: trueThis will automatically inject the following into the <head>:
<link rel="preconnect" href="https://fonts.googleapis.com" crossorigin>
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>List of JS file names to preload (without hash), or a function to dynamically resolve them based on the current HTML page path.
criticalJs: ['main', 'app']This will match files like:
/assets/main-abc123.js/assets/app-def456.js
criticalJs: (path) => {
if (path === '/index.html') return ['main']
if (path.includes('/blog/')) return ['blog']
return []
}This allows per-page targeting in multi-page apps.
Same as criticalJs, but for generated CSS files.
criticalCss: ['main', 'style']Matches:
/assets/main-abc123.css/assets/style-xyz789.css
criticalCss: (path) => {
if (path === '/index.html') return ['main']
if (path.includes('/blog/')) return ['blog']
return []
}- The plugin runs during the build phase (using the
transformIndexHtmlhook) - It scans the HTML and the Vite bundle
- It injects
<link rel="preload">tags at the very beginning of the<head>(head-prepend)
Using preload can improve perceived performance — but only when used wisely.
Here are some tips:
- Only preload what’s essential
- Don’t use
preloadon all images — this can unnecessarily overload the network. - Preload only:
- Critical fonts used immediately
- Images visible above the fold
- JS or CSS files required for the initial render
- Avoid preloading secondary assets
- Do not preload decorative background images or non-critical assets.
- Don’t preload all JS chunks — use
criticalJsonly for main entry files. - Don’t replace
prefetchorlazy loading preloadis not a substitute forloading="lazy"on images.
Goal: help the browser prioritize the loading of truly critical resources — not to load everything upfront, which can have the opposite effect.
MIT License — Free to use, modify, and distribute.