rollup-plugin-modulepreload

2.0.0 verified Mon Apr 27 auth: no javascript

Rollup plugin that adds modulepreload link tags to HTML files for dynamically imported chunks, improving loading performance by hinting the browser to preload ES modules before they are needed. Current version 2.0.0 (released 2021, maintained). Allows customization of which chunks to preload via a synchronous or asynchronous predicate, with default that preloads dynamic entry points and intermediate chunks with exports. Differentiates from generic HTML injectors by focusing specifically on modulepreload semantics and Rollup's chunk metadata.

Common errors

error Error: Could not resolve 'rollup-plugin-modulepreload' ↓

cause Package not installed or not in node_modules.

fix

Run npm install rollup-plugin-modulepreload --save-dev

error TypeError: modulepreload is not a function ↓

cause CommonJS require without .default because the export is a default export.

fix

Use const modulepreload = require('rollup-plugin-modulepreload').default

error Error: [rollup-plugin-modulepreload] Could not read index.html at path '...' ↓

cause The index option points to a non-existent or unreadable file.

fix

Ensure the index file exists and the path is relative to the project root (not the output directory).

error Error: [rollup-plugin-modulepreload] No output directory specified. Please set output.dir or output.preserveModules ↓

cause The plugin requires output.dir to be set in Rollup config.

fix

Add output.dir to your Rollup output options.

Warnings

gotcha If the index option is not specified, the plugin still runs but does not inject anything into an HTML file. It only works if the output.dir is set. ↓

fix Provide an index path (relative to project root) or use output.dir and ensure index exists.

gotcha The default predicate preloads chunks with exports and no facadeModuleId (intermediate chunks), which may include many internal chunks that are never directly imported. This can increase link tag count and network requests. ↓

fix Override shouldPreload to restrict to certain chunks based on your app's structure.

gotcha The prefix option defaults to output.dir, which may not be a web-accessible path. If output.dir is absolute or relative, the link href may be incorrect. ↓

fix Explicitly set prefix to a URL path (e.g., 'modules') that matches where chunks are served from.

gotcha Asynchronous shouldPreload functions can cause the plugin to run slower because they are awaited for each chunk. Ensure your async predicate is performant. ↓

fix Use synchronous predicate if possible, or cache file reads.

Install

npm install rollup-plugin-modulepreload

yarn add rollup-plugin-modulepreload

pnpm add rollup-plugin-modulepreload

Imports

modulepreload
```
import modulepreload from 'rollup-plugin-modulepreload'
```
The plugin is exported as a default function, not a named export.

modulepreload

wrong

const modulepreload = require('rollup-plugin-modulepreload')

correct

const modulepreload = require('rollup-plugin-modulepreload').default

In CommonJS, the default export is under .default property.

type Options
```
import type { Options } from 'rollup-plugin-modulepreload'
```
TypeScript types are shipped and include an Options interface.

Quickstart

Demonstrates basic usage with Rollup config: sets up modulepreload for all chunks, writes <link modulepreload> tags into public/index.html.

import modulepreload from 'rollup-plugin-modulepreload';

export default {
  input: 'src/index.js',
  output: {
    dir: 'public/modules',
    format: 'es',
    entryFileNames: '[name]-[hash].js',
    chunkFileNames: 'chunk-[hash].js',
  },
  plugins: [
    modulepreload({
      prefix: 'modules',
      index: 'public/index.html',
    })
  ]
};