preload-webpack-plugin

2.3.0 verified Sat Apr 25 auth: no javascript

Preload-webpack-plugin (v2.3.0) enhances html-webpack-plugin by adding link rel=preload and prefetch resource hints for scripts and other assets. It integrates with webpack 3 and is developed by Google Chrome Labs. The v3 alpha/beta branches add webpack 4 support and target node >= 6. Key differentiators: automatic preloading of async chunks, granular control via include/exclude options, and support for multiple HtmlWebpackPlugin instances. Unlike manual preloading, it covers all script types (initial, async, dynamic) with minimal config.

Common errors

error TypeError: Cannot read property 'hooks' of undefined ↓

cause Plugin used with webpack 4+ but v2.x does not support webpack 4 hooks.

fix

Use v3.0.0 alpha/beta (npm install preload-webpack-plugin@next) or downgrade webpack to v3.

error Error: 'rel' option is required ↓

cause PreloadWebpackPlugin instantiated without `rel` option.

fix

Add rel: 'preload' or rel: 'prefetch' to the plugin options.

error Module not found: Error: Can't resolve 'html-webpack-plugin' ↓

cause html-webpack-plugin not installed as a dependency.

fix

Run npm install --save-dev html-webpack-plugin.

Warnings

gotcha Must specify at least `rel` option (e.g., 'preload' or 'prefetch'). ↓

fix new PreloadWebpackPlugin({ rel: 'preload', ... })

breaking v3.0.0 drops support for node < 6; requires html-webpack-plugin v4+. ↓

fix Upgrade node to version >=6, use html-webpack-plugin v4 or later.

deprecated Plugin is not compatible with webpack 5; v3.0.0 alphas target webpack 4 only. ↓

fix Consider alternative like @vue/preload-webpack-plugin or use webpack 4.

gotcha `include: 'allAssets'` may include CSS, fonts, etc.; not just scripts. ↓

fix Use `include: 'asyncChunks'` or `include: 'initial'` for scripts only.

gotcha Multiple HtmlWebpackPlugin instances require separate PreloadWebpackPlugin instance per HTML file. ↓

fix Add a new PreloadWebpackPlugin for each HtmlWebpackPlugin.

Install

npm install preload-webpack-plugin

yarn add preload-webpack-plugin

pnpm add preload-webpack-plugin

Imports

PreloadWebpackPlugin
```
const PreloadWebpackPlugin = require('preload-webpack-plugin');
```
CommonJS require; ESM import not supported in v2.x.

PreloadWebpackPlugin

wrong

import { PreloadWebpackPlugin } from 'preload-webpack-plugin';

correct

import PreloadWebpackPlugin from 'preload-webpack-plugin';

Default export; named import will fail.

plugins array

wrong

new PreloadWebpackPlugin()

correct

new PreloadWebpackPlugin({ rel: 'preload', include: 'asyncChunks' })

Options are required; at least 'rel' must be specified.

Quickstart

Configure webpack to preload async chunks via html-webpack-plugin.

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

module.exports = {
  entry: './src/index.js',
  output: { filename: '[name].[hash].js' },
  plugins: [
    new HtmlWebpackPlugin(),
    new PreloadWebpackPlugin({
      rel: 'preload',
      include: 'asyncChunks',
      fileWhitelist: [/\/dist\/.*\.js/]
    })
  ]
};