webpack-font-preload-plugin

1.5.0 verified Sat Apr 25 auth: no javascript

A webpack plugin that automatically adds preload or prefetch links for font assets to the HTML output, improving page load performance by prioritizing font loading. Current stable version is 1.5.0, with a 2.0.0-beta.0 release in development. Release cadence is irregular. Key differentiators: zero-config for most webpack setups, supports both webpack 4 and 5, provides filtering and custom HTML replacement callbacks. Built-in TypeScript types since v1.4.0. Requires jsdom and webpack-sources as dependencies.

Common errors

error TypeError: Cannot read properties of undefined (reading 'tapAsync') ↓

cause Incompatibility with webpack 5 hooks in versions before 2.0.0-beta.0.

fix

Upgrade to version 2.0.0-beta.0 or later, or use a hook shim. Alternatively, stick with webpack 4.

error Error: Property 'apply' is missing in type 'WebpackFontPreloadPlugin' ↓

cause Incorrect usage in webpack 5 with older plugin versions (before v1.4.1).

fix

Upgrade to v1.4.1+ or use the correct instantiation: new WebpackFontPreloadPlugin() without extra options.

error Module not found: Error: Can't resolve 'jsdom' ↓

cause Missing jsdom dependency since v1.3.0.

fix

Install jsdom: npm install jsdom --save-dev

Warnings

breaking In v1.4.0, the TypeScript types were added, changing the import behavior for TypeScript users. Previously, the plugin had no types. ↓

fix If using TypeScript, import the default export as described. No further changes needed.

gotcha The plugin relies on jsdom to parse and modify HTML. Ensure jsdom is installed as a dependency. ↓

fix Run npm install jsdom to add it explicitly if not included by npm automatically.

gotcha The plugin requires HtmlWebpackPlugin to be present in the plugins array; otherwise, no HTML file is generated and fonts are not preloaded. ↓

fix Add new HtmlWebpackPlugin() to your webpack plugins array.

deprecated The publicPath option might not work as expected if set to an empty string; fixed in v1.4.1. ↓

fix Upgrade to v1.4.1 or later, or ensure publicPath is a non-empty string.

Install

npm install webpack-font-preload-plugin

yarn add webpack-font-preload-plugin

pnpm add webpack-font-preload-plugin

Imports

default

wrong

const WebpackFontPreloadPlugin = require('webpack-font-preload-plugin').default

correct

import WebpackFontPreloadPlugin from 'webpack-font-preload-plugin'

ESM default export; in CJS, use require('webpack-font-preload-plugin') which returns the class directly.

WebpackFontPreloadPlugin

wrong

import { WebpackFontPreloadPlugin } from 'webpack-font-preload-plugin'

correct

import WebpackFontPreloadPlugin from 'webpack-font-preload-plugin'

The plugin is a default export, not a named export.

type Options
```
import type { Options } from 'webpack-font-preload-plugin'
```
TypeScript types exported; Options type available since v1.4.0.

Quickstart

Basic webpack configuration to preload font files. Shows plugin setup with HtmlWebpackPlugin, file-loader for fonts, and preload option.

const WebpackFontPreloadPlugin = require('webpack-font-preload-plugin');
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    path: __dirname + '/dist',
    filename: 'bundle.js'
  },
  module: {
    rules: [
      {
        test: /\.(woff|woff2|eot|ttf|otf)$/,
        use: ['file-loader']
      }
    ]
  },
  plugins: [
    new HtmlWebpackPlugin(),
    new WebpackFontPreloadPlugin({
      // Options: 'preload' or 'prefetch'
      rel: 'preload',
      // Optional: filter fonts by regex
      filter: /fonts\/.*\.woff2$/
    })
  ]
};