quicklink

quicklink

Faster subsequent page-loads by prefetching or prerendering in-viewport links during idle time

How it works

Quicklink attempts to make navigations to subsequent pages load faster. It:

• Detects links within the viewport (using Intersection Observer)
• Waits until the browser is idle (using requestIdleCallback)
• Checks if the user isn't on a slow connection (using navigator.connection.effectiveType) or has data-saver enabled (using navigator.connection.saveData)
• Prefetches (using <link rel=prefetch> or XHR) or prerenders (using Speculation Rules API) URLs to the links. Provides some control over the request priority (can switch to fetch() if supported).

Why

This project aims to be a drop-in solution for sites to prefetch or prerender links based on what is in the user's viewport. It also aims to be small (< 2KB minified/gzipped).

Multi page apps

Installation

For use with Node.js and npm:

npm install quicklink

You can also grab quicklink from unpkg.com/quicklink.

Usage

Once initialized, quicklink will automatically prefetch URLs for links that are in-viewport during idle time.

Quickstart:

<script src="dist/quicklink.umd.js"></script>

<script>
  quicklink.listen();
</script>

For example, you can initialize after the load event fires:

<script>
  window.addEventListener('load', () => {
    quicklink.listen();
  });
</script>

ES Module import:

import {listen, prefetch} from 'quicklink';

Modern ES Module (quicklink.modern.mjs) — a smaller build for browsers with native ES module support (no legacy transforms). Prefer this when you only need to support modern browsers:

import {listen, prefetch} from 'quicklink/dist/quicklink.modern.mjs';

Single page apps (React)

Installation

First, install the packages with Node.js and npm:

npm install quicklink webpack-route-manifest --save-dev

Then, configure Webpack route manifest into your project, as explained in the webpack-route-manifest docs. This will generate a map of routes and chunks called rmanifest.json. It can be obtained at:

• URL: site_url/rmanifest.json
• Window object: window.__rmanifest

Usage

Import quicklink React HOC where want to add prefetching functionality. Wrap your routes with the withQuicklink() HOC.

Example:

import {withQuicklink} from 'quicklink/dist/react/hoc.js';

const options = {
  origins: [],
};

<Suspense fallback={
}>
  <Route path='/' exact component={withQuicklink(Home, options)} />
  <Route path='/blog' exact component={withQuicklink(Blog, options)} />
  <Route path='/blog/:title' component={withQuicklink(Article, options)} />
  <Route path='/about' exact component={withQuicklink(About, options)} />
</Suspense>;

API

quicklink.listen(options)

Returns: Function

A "reset" function is returned, which will empty the active IntersectionObserver and the cache of URLs that have already been prefetched or prerendered. This can be used between page navigations and/or when significant DOM changes have occurred.

options.prerender

• Type: Boolean
• Default: false

Whether to switch from the default prefetching mode to the prerendering mode for the links inside the viewport.

Note: The prerendering mode (when this option is set to true) will fallback to the prefetching mode if the browser does not support prerender. Once the element exits the viewport, the speculationrules script is removed from the DOM. This approach makes it possible to exceed the limit of 10 prerenders imposed for the 'immediate' and 'eager' settings for eagerness.

options.eagerness

• Type: String
• Default: immediate

Determines the mode to be used for prerendering specified within the speculation rules.

options.prerenderAndPrefetch

• Type: Boolean
• Default: false

Whether to activate both the prefetching and prerendering mode at the same time.

options.delay

• Type: Number
• Default: 0

The amount of time each link needs to stay inside the viewport before being prefetched, in milliseconds.

options.el

• Type: HTMLElement|NodeList<A>
• Default: document.body

The DOM element to observe for in-viewport links to prefetch or the NodeList of Anchor Elements.

options.limit

• Type: Number
• Default: Infinity

The total requests that can be prefetched or prerendered while observing the options.el container.

options.threshold

• Type: Number
• Default: 0

The area percentage of each link that must have entered the viewport to be fetched, in its decimal form (e.g. 0.25 = 25%).

options.throttle

• Type: Number
• Default: Infinity

The concurrency limit for simultaneous requests while observing the options.el container.

options.timeout

• Type: Number
• Default: 2000

The requestIdleCallback timeout, in milliseconds.

Note: The browser must be idle for the configured duration before prefetching.

options.timeoutFn

• Type: Function
• Default: requestIdleCallback

A function used for specifying a timeout delay.

This can be swapped out for a custom function like networkIdleCallback (see demos).

By default, this uses requestIdleCallback or the embedded polyfill.

options.priority

• Type: Boolean
• Default: false

Whether or not the URLs within the options.el container should be treated as high priority.

When true, quicklink will attempt to use the fetch() API if supported (rather than link[rel=prefetch]).

options.origins

• Type: Array<String>
• Default: [location.hostname]

A static array of URL hostnames that are allowed to be prefetched.

Defaults to the same domain origin, which prevents any cross-origin requests.

Important: An empty array ([]) allows all origins to be prefetched.

options.ignores

• Type: RegExp or Function or Array
• Default: []

Determine if a URL should be prefetched.

When a RegExp tests positive, a Function returns true, or an Array contains the string, then the URL is not prefetched.

Note: An Array may contain String, RegExp, or Function values.

Important: This logic is executed after origin matching!

options.onError

• Type: Function
• Default: None

An optional error handler that will receive any errors from prefetched requests.

By default, these errors are silently ignored.

options.hrefFn

• Type: Function
• Default: None

An optional function to generate the URL to prefetch. It receives an Element as the argument.

quicklink.prefetch(urls, isPriority)

Returns: Promise

The urls provided are always passed through Promise.all, which means the result will always resolve to an Array.

Important: You much catch you own request error(s).

urls

• Type: String or Array<String>
• Required: true

One or many URLs to be prefetched.

Note: Each url value is resolved from the current location.

isPriority

• Type: Boolean
• Default: false

Whether or not the URL(s) should be treated as "high priority" targets.

By default, calls to prefetch() are low priority.

Note: This behaves identically to listen()'s priority option.

quicklink.prerender(urls, eagerness)

Returns: Promise

Important: You much catch you own request error(s).

urls

• Type: String or Array<String>
• Required: true

One or many URLs to be prerendered.

Note: Speculative Rules API supports same-site cross origin Prerendering with opt-in header.

eagerness

• Type: String
• Default: immediate

Determines the mode to be used for prerendering specified within the speculation rules.

Polyfills

quicklink:

• Includes a very small fallback for requestIdleCallback
• Requires IntersectionObserver to be supported. This is supported in all modern browsers, however you can use the Intersection Observer polyfill to support legacy browsers if needed.

Recipes

Set a custom timeout for prefetching resources

Defaults to 2 seconds (via requestIdleCallback). Here we override it to 4 seconds:

quicklink.listen({
  timeout: 4000,
});

Set a specific Anchor Elements NodeList to observe for in-viewport links

Defaults to document otherwise.

quicklink.listen({
  el: document.querySelectorAll('a.linksToPrefetch'),
});

Set the DOM element to observe for in-viewport links

Defaults to document otherwise.

quicklink.listen({
  el: document.getElementById('carousel'),
});

Programmatically prefetch() URLs

If you would prefer to provide a static list of URLs to be prefetched, instead of detecting those in-viewport, customizing URLs is supported.

// Single URL
quicklink.prefetch('2.html');

// Multiple URLs
quicklink.prefetch(['2.html', '3.html', '4.js']);

// Multiple URLs, with high priority
// Note: Can also be use with single URL!
quicklink.prefetch(['2.html', '3.html', '4.js'], true);

Programmatically prerender() URLs

If you would prefer to provide a static list of URLs to be prerendered, instead of detecting those in-viewport, customizing URLs is supported.

// Single URL
quicklink.prerender('2.html');

// Multiple URLs
quicklink.prerender(['2.html', '3.html', '4.js']);

Set the request priority for prefetches while scrolling

Defaults to low-priority (rel=prefetch or XHR). For high-priority (priority: true), attempts to use fetch() or falls back to XHR.

Note: This runs prefetch(..., true) with URLs found within the options.el container.

quicklink.listen({priority: true});

Specify a custom list of allowed origins

Provide a list of hostnames that should be prefetch-able. Only the same origin is allowed by default.

Important: You must also include your own hostname!

quicklink.listen({
  origins: [
    // add mine
    'my-website.com',
    'api.my-website.com',
    // add third-parties
    'other-website.com',
    'example.com',
    // ...
  ],
});

Allow all origins

Enables all cross-origin requests to be made.

Note: You may run into CORB and CORS issues!

quicklink.listen({
  origins: true,
  // or
  origins: [],
});

Custom Ignore Patterns

By default, quicklink skips anchors that have a download attribute, since those often point at large binary payloads.

These filters run after the origins matching has run