Quicklink

To prevent inflating Ad CTR (click-through-rate) by unintentionally counting prefetch requests as clicks, follow these guidelines:

1. If ads are in iframes: Quicklink will not prefetch them by default because the lookup is restricted to the top-level origin.
2. If ads are outside iframes (same-origin): You must explicitly tell Quicklink to avoid them by adding the ad-link URL, subpath, or the containing element to the ignores list in quicklink.listen().

In a Single-Page Application (SPA), links typically navigate between routes using JavaScript rather than requesting new HTML documents. To make Quicklink work effectively in this environment, you must provide an hrefFn option. This function maps a standard link's href to the actual URL of the JavaScript chunk required for that route. This ensures Quicklink prefetches the necessary code instead of attempting to fetch an HTML document that won't be used for navigation.

// Example pattern for an SPA
quicklink.listen({
  hrefFn: (url) => {
    // Map the route URL to the specific JS chunk URL
    return `/chunks/${url}.js`;
  }
});

quicklink speeds up subsequent page loads by prefetching or prerendering links that are currently in the user's viewport during browser idle time.

It follows these steps:

1. Detects links in viewport: Uses the Intersection Observer API.
2. Waits for idle time: Uses requestIdleCallback to ensure prefetching doesn't interfere with critical tasks.
3. Checks connection quality: Uses navigator.connection.effectiveType and navigator.connection.saveData to avoid prefetching on slow connections or when data-saver is enabled.
4. Executes prefetch/prerender: Uses <link rel=prefetch> or XHR for prefetching, or the Speculation Rules API for prerendering. It can also use fetch() for high-priority requests if supported.

To set up the canonical site source for Quicklink, clone the repository, navigate to the site directory, and install the dependencies using npm.

git clone git@github.com:googlechromelabs/quicklink.git
cd site
npm install

To use quicklink in a standard multi-page website via Node.js and npm, install the package using the following command:

npm install quicklink

You can also access it via unpkg.com/quicklink.

Quicklink supports three primary modes of operation:

1. Prefetching (Default): Downloads the resource in the background. This is widely supported and uses standard fetch mechanisms.
2. Prerendering: Uses the Speculation Rules API to actually render the page in a hidden state, making navigation nearly instantaneous. This is used when options.prerender is true.
3. Hybrid Mode: When options.prerenderAndPrefetch is true, the library attempts to use both.

Warning: If you call prefetch() and prerender() manually on the same document without setting prerenderAndPrefetch: true, a warning will be logged to the console: [Warning] You are using both prefetching and prerendering on the same document.

The ignores option accepts FilterMatcher values to exclude specific links from prefetching. A matcher can be:

1. RegExp: Tests against the full URL (node.href).
2. Function: Receives (href: string, node: Element) as arguments.
3. Array: An array of any of the above.

Example of a function matcher:

// Ignore links that point to a specific section or have a specific class
const myFilter = (href, node) => node.classList.contains('no-prefetch');

listen({ ignores: [myFilter] });

You can import the prefetch method as a standalone module to use in your own projects. This is useful for manual control over prefetching logic.

<script type="module">
  import {prefetch} from 'quicklink';
  prefetch(['1.html', '2.html']).catch(error => {
    // Handle own errors
  });
</script>