unplugin-inject-preload

3.0.0 verified Sat Apr 25 auth: no javascript

Universal plugin to inject <link rel='preload'> tags into HTML output for Vite 4/5, Webpack 5 (with HtmlWebpackPlugin), and Rspack 1.0 (with HtmlWebpackPlugin or HtmlRspackPlugin). Current stable version is 3.0.0, released with Rspack 1.0 support and dropped support for Rspack 0.x. Replaces separate packages vite-plugin-inject-preload and html-webpack-inject-preload. Ships TypeScript types. Release cadence is irregular, with minor releases featuring breaking changes. Key differentiator: single unified API across multiple bundlers.

Common errors

error Cannot find module 'unplugin-inject-preload/vite' ↓

cause Missing subpath export or using wrong bundler-specific import.

fix

Ensure you are using the correct import path: 'unplugin-inject-preload/vite', '/webpack', or '/rspack'. Also verify the package is installed.

error TypeError: UnpluginInjectPreload is not a function ↓

cause Importing from a wrong path or using a default import when only named export exists.

fix

Use default import: import UnpluginInjectPreload from 'unplugin-inject-preload/vite'

error Error: html-webpack-plugin is required as a peer dependency ↓

cause Missing html-webpack-plugin for Webpack/Rspack builds.

fix

Install html-webpack-plugin@>=5.0.0 as a devDependency.

Warnings

breaking Drop support for Rspack 0.x versions. v3.0.0 only supports Rspack 1.0. ↓

fix Upgrade Rspack to 1.0.x or later. For Rspack 0.x, stick with v2.x.

breaking Drop support for Vite 3. v2.0.0 requires Vite 4 or 5. ↓

fix Upgrade to Vite 4 or 5.

deprecated Rollup 4 (shipped with Vite 5) uses base64 hashes in file names instead of base16 hashes. This may break `outputMatch` patterns expecting base16. ↓

fix Update your `outputMatch` regex to handle base64 hashes (e.g., allow longer alphanumeric strings).

gotcha The Vite plugin only works on build (not dev server). Assets are not available during development. ↓

fix Test preload injection with `vite build` only. Dev server will not inject preload links.

Install

npm install unplugin-inject-preload

yarn add unplugin-inject-preload

pnpm add unplugin-inject-preload

Imports

UnpluginInjectPreload
wrong
```
const UnpluginInjectPreload = require('unplugin-inject-preload')
```
correct
```
import UnpluginInjectPreload from 'unplugin-inject-preload/vite'
```
Import from subpath /vite for Vite, /webpack for Webpack, /rspack for Rspack. The plugin is ESM-only; CommonJS require may fail depending on bundler.

UnpluginInjectPreload

wrong

const UnpluginInjectPreload = require('unplugin-inject-preload/webpack')

correct

import UnpluginInjectPreload from 'unplugin-inject-preload/webpack'

For Webpack: use subpath /webpack. Requires html-webpack-plugin ≥5.0.0.

UnpluginInjectPreload

wrong

const UnpluginInjectPreload = require('unplugin-inject-preload/rspack')

correct

import UnpluginInjectPreload from 'unplugin-inject-preload/rspack'

For Rspack: use subpath /rspack. Supports both HtmlWebpackPlugin and HtmlRspackPlugin.

UnpluginInjectPreload
```
import UnpluginInjectPreload from 'unplugin-inject-preload'
```
Direct import exists but returns a generic factory; prefer specific subpath for clarity.

Quickstart

Configure Vite to inject preload links for all .woff2 and .woff font files built by the bundler.

// For Vite: vite.config.ts
import UnpluginInjectPreload from 'unplugin-inject-preload/vite';

export default defineConfig({
  plugins: [
    UnpluginInjectPreload({
      files: [
        {
          match: /\.(woff2|woff)$/,
        },
      ],
    }),
  ],
});