EN | FR

vite-plugin-preload-assets

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.

Features

📷 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

Installation

npm install vite-plugin-preload-assets --save-dev

Utilisation

In 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']
        })
    ]
}

Image Preloading

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">

Support for dark mode variants

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.

Available options

imagesToPreload

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">

fontsToPreload

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 as attribute ('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 a is not set to 'font', the plugin will automatically skip the type attribute to avoid preload warnings.

preloadGoogleFonts

Automatically injects the preconnect tags needed to optimize the loading of Google Fonts:

preloadGoogleFonts: true

This 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>

criticalJs

List of JS file names to preload (without hash), or a function to dynamically resolve them based on the current HTML page path.

Basic usage (array):

criticalJs: ['main', 'app']

This will match files like:

/assets/main-abc123.js
/assets/app-def456.js

Advanced usage (per page):

criticalJs: (path) => {
  if (path === '/index.html') return ['main']
  if (path.includes('/blog/')) return ['blog']
  return []
}

This allows per-page targeting in multi-page apps.

criticalCss

Same as criticalJs, but for generated CSS files.

Basic usage (array):

criticalCss: ['main', 'style']

Matches:

/assets/main-abc123.css
/assets/style-xyz789.css

Advanced usage (per page):

criticalCss: (path) => {
  if (path === '/index.html') return ['main']
  if (path.includes('/blog/')) return ['blog']
  return []
}

How it works

The plugin runs during the build phase (using the transformIndexHtml hook)
It scans the HTML and the Vite bundle
It injects <link rel="preload"> tags at the very beginning of the <head> (head-prepend)

Best Practices

Using preload can improve perceived performance — but only when used wisely.

Here are some tips:

Only preload what’s essential
Don’t use preload on 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 criticalJs only for main entry files.
Don’t replace prefetch or lazy loading
preload is not a substitute for loading="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.

License

MIT License — Free to use, modify, and distribute.