11ty Plugin: Speculation Rules

npm npm license

This plugin adds support for the Speculation Rules API, which allows defining rules by which certain URLs are dynamically prefetched or prerendered based on user interaction.

Installation

Install the plugin from npm:

npm install eleventy-plugin-speculation-rules --save-dev

Configuration

mode - The speculation mode.
Default: prerender, options: prefetch, prerender
eagerness - The eagerness level for speculation.
Default: moderate, options: conservative, moderate, eager
noPrerenderSelector - CSS selector for links that should not be prerendered.
Default: .no-prerender
include - Array of URL patterns to include.
Default: []
exclude - Array of URL patterns to exclude.
Default: []

By default, the plugin excludes .zip and .pdf files, as well as links with rel="nofollow".

Usage

Add it to your Eleventy Config file:

ESM (Eleventy 3.x):

import eleventyPluginSpeculationRules from 'eleventy-plugin-speculation-rules';

export default function (eleventyConfig) {
    eleventyConfig.addPlugin(eleventyPluginSpeculationRules);
};

CommonJS (Eleventy 2.x):

const eleventyPluginSpeculationRules = require('eleventy-plugin-speculation-rules');

module.exports = function (eleventyConfig) {
    eleventyConfig.addPlugin(eleventyPluginSpeculationRules);
};

Advanced usage:

import eleventyPluginSpeculationRules from 'eleventy-plugin-speculation-rules';

export default function (eleventyConfig) {
    eleventyConfig.addPlugin(eleventyPluginSpeculationRules, {
        mode: 'prefetch',
        eagerness: 'eager',
        noPrerenderSelector: '.no-prerender',
        include: ['/blog/*'],
        exclude: ['/admin/*']
    });
};

Speculation Mode

prefetch - The browser will prefetch the URL when the user hovers over the link.
prerender - The browser will prerender the URL when the user hovers over the link.

Prerendering will lead to faster load times than prefetching. However, in case of interactive content, prefetching may be a safer choice.

Speculation Eagerness

conservative - Speculates only on click
moderate - Speculates on hover
eager - Speculates on slightest indication

The eagerness setting defines the heuristics based on which the loading is triggered. "Eager" will have the minimum delay to start speculative loads, "Conservative" increases the chance that only URLs the user actually navigates to are loaded.

Demo

Does it work?

Check the network tab in your browser's developer tools to see if the page is prefetched or prerendered.

More information about the Speculation Rules API can be found here.

More about Debugging speculation rules.

Browser support

The Speculation Rules API is a new web API, and the functionality used by the plugin is supported in Chromium-based browsers such as Chrome, Edge, or Opera using version 121 or above. Other browsers such as Safari and Firefox will ignore the functionality with no ill effects but will not benefit from the speculative loading. Note that extensions may disable preloading by default (for example, uBlock Origin does this).

License

MIT License