unplugin-inject-preload

This plugin adds preload links by getting output assets from the build tools you are using.

Supporting:

• Vite 4 and 5 (on build only)
• Webpack 5 (with HtmlWebpackPlugin 5)
• Rspack 1.0 (with HtmlWebpackPlugin 5 or HtmlRspackPlugin)

[!NOTE] This plugin combines vite-plugin-inject-preload and html-webpack-inject-preload into one package.

See the migration guide for vite-plugin-inject-preload and html-webpack-inject-preload .

Install

1#npm
2npm i -D unplugin-inject-preload
3#yarn
4yarn add -D unplugin-inject-preload
5#pnpm
6pnpm i -D unplugin-inject-preload

1// vite.config.ts
2import UnpluginInjectPreload from 'unplugin-inject-preload/vite'
3
4export default defineConfig({
5  plugins: [
6    UnpluginInjectPreload({ /* options */ }),
7  ],
8})

1// webpack.config.js
2const HtmlWebpackPlugin = require('html-webpack-plugin')
3const UnpluginInjectPreload = require('unplugin-inject-preload/webpack')
4
5module.exports = {
6  plugins: [
7    HtmlWebpackPlugin({ /*  HtmlWebpackPlugin options */ }),
8    UnpluginInjectPreload({ /* options */ }),
9  ]
10}

1// rspack.config.js
2const HtmlWebpackPlugin = require('html-webpack-plugin')
3const UnpluginInjectPreload = require('unplugin-inject-preload/rspack')
4
5module.exports = {
6  plugins: [
7    HtmlWebpackPlugin({ /*  HtmlWebpackPlugin options */ }),
8    UnpluginInjectPreload({ /* options */ }),
9  ]
10}

1// rspack.config.js
2const HtmlWebpackPlugin = require('html-webpack-plugin')
3const UnpluginInjectPreload = require('unplugin-inject-preload/rspack')
4
5module.exports = {
6  plugins: [
7    new rspack.HtmlRspackPlugin({ /* HtmlRspackPlugin options */ }),
8    UnpluginInjectPreload({ /* options */ }),
9  ]
10}

👨‍💻 Usage

All example are presented for ViteJS but this is the same behavior for Webpack and RsPack

All the files needs to be process by the bundler to be find by the plugin. For example, if I load this CSS file :

1@font-face {
2  font-family: 'Roboto';
3  src: url('./../fonts/Roboto-Italic.woff2');
4  font-weight: 400;
5  font-style: italic;
6}
7
8@font-face {
9  font-family: 'Roboto';
10  src: url('./../fonts/Roboto-Regular.woff2');
11  font-weight: 400;
12  font-style: normal;
13}

I can make the following configuration for UnpluginInjectPreload :

1// vite.config.js / vite.config.ts
2import UnpluginInjectPreload from 'unplugin-inject-preload/vite'
3
4export default {
5  plugins: [
6    UnpluginInjectPreload({
7      files: [
8        {
9          entryMatch: /Roboto-[a-zA-Z]*\.woff2$/,
10        },
11        {
12          outputMatch: /lazy.[a-z-0-9]*.(css|js)$/,
13        }
14      ]
15    })
16  ]
17}

Options

• files: An array of files object

  • entryMatch: A regular expression to target entry files you want to preload
  • outputMatch: A regular expression to target output build files you want to preload

  You need to set at least entryMatch or/and outputMatch. Be aware that entry file is not always present for webpack and entryMatch will do nothing.

  • attributes (optional): If this option is ommited, it will determine the mime and the as attributes automatically. You can also add/override any attributes you want.

• injectTo (optional): By default, the preload links are injected with the 'head-prepend' options. But you can pass 'head' to inject preload links at bottom of the head tag if you need it.
  You can pass the 'custom' option and put <!--__unplugin-inject-preload__--> in your .html file where you want to inject the preload links.

With the full options usage, you can do something like this :

1// vite.config.js / vite.config.ts
2import UnpluginInjectPreload from 'unplugin-inject-preload/vite'
3
4export default {
5  plugins: [
6    UnpluginInjectPreload({
7      files: [
8        {
9          entryMatch: /Roboto-[a-zA-Z]*\.woff2$/,
10          outputMatch: /Roboto-[a-zA-Z]*-[a-z-0-9]*\.woff2$/,
11          attributes: {
12            'type': 'font/woff2',
13            'as': 'font',
14            'crossorigin': 'anonymous',
15            'data-font': 'Roboto'
16          }
17        },
18        {
19          outputMatch: /lazy.[a-z-0-9]*.(js)$/,
20          attributes: {
21            rel: 'modulepreload',
22            type: undefined,
23          }
24        }
25      ],
26      injectTo: 'head-prepend'
27    })
28  ]
29}

Migration

From vite-plugin-inject-preload

package.json

1{
2  "devDependencies": {
3-   "vite-plugin-inject-preload": "*",
4+   "unplugin-inject-preload": "^3.0.0",
5  }
6}

vite.config.js

1- import VitePluginInjectPreload from 'vite-plugin-inject-preload'
2+ import UnpluginInjectPreload from 'unplugin-inject-preload/vite'
3
4export default {
5  plugins: [
6-   VitePluginInjectPreload({
7+   UnpluginInjectPreload({
8      files: [
9        {
10-         match: /Roboto-[a-zA-Z]*-[a-z-0-9]*\.woff2$/,
11+         outputMatch: /Roboto-[a-zA-Z]*-[a-z-0-9]*\.woff2$/,
12          attributes: {
13            'type': 'font/woff2',
14            'as': 'font',
15            'crossorigin': 'anonymous',
16            'data-font': 'Roboto'
17          }
18        },
19      ],
20      injectTo: 'head-prepend'
21    })
22  ]
23}

From html-webpack-inject-preload

package.json

1{
2  "devDependencies": {
3-   "@principalstudio/html-webpack-inject-preload": "*",
4+   "unplugin-inject-preload": "^3.0.0",
5  }
6}

1const HtmlWebpackPlugin = require('html-webpack-plugin');
2- const HtmlWebpackInjectPreload = require('@principalstudio/html-webpack-inject-preload');
3+ const UnpluginInjectPreload = require('unplugin-inject-preload/webpack');
4
5module.exports = {
6  entry: 'index.js',
7  output: {
8    path: __dirname + '/dist',
9    filename: 'index_bundle.js'
10  },
11  plugins: [
12    new HtmlWebpackPlugin(),
13-   new HtmlWebpackInjectPreload({
14+   UnpluginInjectPreload({
15      files: [
16        {
17-         match: /.*\.woff2$/,
18+         outputMatch: /.*\.woff2$/,
19          attributes: {
20            as: 'font',
21            type: 'font/woff2', crossorigin: true
22          },
23        },
24      ]
25    })
26  ]
27}

👨‍💼 Licence

MIT