Home

Awesome

unplugin-inject-preload

NPM Version jsr node-current Coverage Status

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

Supporting:

[!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

#npm
npm i -D unplugin-inject-preload
#yarn
yarn add -D unplugin-inject-preload
#pnpm
pnpm i -D unplugin-inject-preload
<details> <summary>Vite</summary><br>
// vite.config.ts
import UnpluginInjectPreload from 'unplugin-inject-preload/vite'

export default defineConfig({
  plugins: [
    UnpluginInjectPreload({ /* options */ }),
  ],
})

Example: playground/vitejs

The Vite plugin only works on build because of the way Vite behave.

<br></details>

<details> <summary>Webpack (with HtmlWebpackPlugin)</summary><br>
// webpack.config.js
const HtmlWebpackPlugin = require('html-webpack-plugin')
const UnpluginInjectPreload = require('unplugin-inject-preload/webpack')

module.exports = {
  plugins: [
    HtmlWebpackPlugin({ /*  HtmlWebpackPlugin options */ }),
    UnpluginInjectPreload({ /* options */ }),
  ]
}

Example: playground/webpack

<br></details>

<details> <summary>Rspack (with HtmlWebpackPlugin)</summary><br>
// rspack.config.js
const HtmlWebpackPlugin = require('html-webpack-plugin')
const UnpluginInjectPreload = require('unplugin-inject-preload/rspack')

module.exports = {
  plugins: [
    HtmlWebpackPlugin({ /*  HtmlWebpackPlugin options */ }),
    UnpluginInjectPreload({ /* options */ }),
  ]
}

Example: playground/rspack

<br></details>

<details> <summary>Rspack (with HtmlRspackPlugin)</summary><br>
// rspack.config.js
const HtmlWebpackPlugin = require('html-webpack-plugin')
const UnpluginInjectPreload = require('unplugin-inject-preload/rspack')

module.exports = {
  plugins: [
    new rspack.HtmlRspackPlugin({ /* HtmlRspackPlugin options */ }),
    UnpluginInjectPreload({ /* options */ }),
  ]
}

Example: playground/rspack

<br></details>

👨‍💻 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 :

@font-face {
  font-family: 'Roboto';
  src: url('./../fonts/Roboto-Italic.woff2');
  font-weight: 400;
  font-style: italic;
}

@font-face {
  font-family: 'Roboto';
  src: url('./../fonts/Roboto-Regular.woff2');
  font-weight: 400;
  font-style: normal;
}

I can make the following configuration for UnpluginInjectPreload :

// vite.config.js / vite.config.ts
import UnpluginInjectPreload from 'unplugin-inject-preload/vite'

export default {
  plugins: [
    UnpluginInjectPreload({
      files: [
        {
          entryMatch: /Roboto-[a-zA-Z]*\.woff2$/,
        },
        {
          outputMatch: /lazy.[a-z-0-9]*.(css|js)$/,
        }
      ]
    })
  ]
}

Options

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

// vite.config.js / vite.config.ts
import UnpluginInjectPreload from 'unplugin-inject-preload/vite'

export default {
  plugins: [
    UnpluginInjectPreload({
      files: [
        {
          entryMatch: /Roboto-[a-zA-Z]*\.woff2$/,
          outputMatch: /Roboto-[a-zA-Z]*-[a-z-0-9]*\.woff2$/,
          attributes: {
            'type': 'font/woff2',
            'as': 'font',
            'crossorigin': 'anonymous',
            'data-font': 'Roboto'
          }
        },
        {
          outputMatch: /lazy.[a-z-0-9]*.(js)$/,
          attributes: {
            rel: 'modulepreload',
            type: undefined,
          }
        }
      ],
      injectTo: 'head-prepend'
    })
  ]
}

Migration

From vite-plugin-inject-preload

package.json

{
  "devDependencies": {
-   "vite-plugin-inject-preload": "*",
+   "unplugin-inject-preload": "^3.0.0",
  }
}

vite.config.js

- import VitePluginInjectPreload from 'vite-plugin-inject-preload'
+ import UnpluginInjectPreload from 'unplugin-inject-preload/vite'

export default {
  plugins: [
-   VitePluginInjectPreload({
+   UnpluginInjectPreload({
      files: [
        {
-         match: /Roboto-[a-zA-Z]*-[a-z-0-9]*\.woff2$/,
+         outputMatch: /Roboto-[a-zA-Z]*-[a-z-0-9]*\.woff2$/,
          attributes: {
            'type': 'font/woff2',
            'as': 'font',
            'crossorigin': 'anonymous',
            'data-font': 'Roboto'
          }
        },
      ],
      injectTo: 'head-prepend'
    })
  ]
}

From html-webpack-inject-preload

package.json

{
  "devDependencies": {
-   "@principalstudio/html-webpack-inject-preload": "*",
+   "unplugin-inject-preload": "^3.0.0",
  }
}
const HtmlWebpackPlugin = require('html-webpack-plugin');
- const HtmlWebpackInjectPreload = require('@principalstudio/html-webpack-inject-preload');
+ const UnpluginInjectPreload = require('unplugin-inject-preload/webpack');

module.exports = {
  entry: 'index.js',
  output: {
    path: __dirname + '/dist',
    filename: 'index_bundle.js'
  },
  plugins: [
    new HtmlWebpackPlugin(),
-   new HtmlWebpackInjectPreload({
+   UnpluginInjectPreload({
      files: [
        {
-         match: /.*\.woff2$/,
+         outputMatch: /.*\.woff2$/,
          attributes: {
            as: 'font',
            type: 'font/woff2', crossorigin: true
          },
        },
      ]
    })
  ]
}

👨‍💼 Licence

MIT