isabella232 / tti-polyfill

Time-to-interactive polyfill

Time to Interactive Polyfill

A polyfill for the Time to Interactive metric. See the metric definition for in-depth implementation details.

Installation

You can install the TTI polyfill from npm by running:

npm install tti-polyfill

Usage

Adding the TTI polyfill is a two-step process. First you need to add a snippet of code to the head of your document (before any other scripts run). This snippet creates a PerformanceObserver instance and starts observing longtask entry types.

<script>
!function(){if('PerformanceLongTaskTiming' in window){var g=window.__tti={e:[]};
g.o=new PerformanceObserver(function(l){g.e=g.e.concat(l.getEntries())});
g.o.observe({entryTypes:['longtask']})}}();
</script>

Note: this snippet is a temporary workaround, until browsers implement level 2 of the Performance Observer spec and include the buffered flag.

The second step is to import the module into your application code and invoke the getFirstConsistentlyInteractive() method. The getFirstConsistentlyInteractive() method returns a promise that resolves to the TTI metric value (in milliseconds since navigation start). If no TTI value can be found, or if the browser doesn't support all the APIs required to detect TTI, the promise resolves to null.

import ttiPolyfill from './path/to/tti-polyfill.js';

ttiPolyfill.getFirstConsistentlyInteractive(opts).then((tti) => {
  // Use `tti` value in some way.
});

Note that this method can be invoked at any time, it does not need to be called prior to interactivity being reached. This allows you to load the polyfill via <script async>, so it doesn't block any other critical resources.

Configuration options

The following table outlines the configuration options you can pass to the getFirstConsistentlyInteractive() method:

Name	Type	Description
minValue	number|null	The lower bound to start forward-searching for the quite window. If no value is set, the default is after the DOMContentLoaded event.
useMutationObserver	boolean	When true (the default), a mutation observer is used to detect when added DOM elements will create additional network requests. This can be disabled to improve performance in cases where you know no additional request-creating DOM elements will be added.

The debug version

A debug version of the polyfill ships with this repo that includes helpful console.log() statements that can be used to better understand how the polyfill is working under the hood.

Note: usage for the debug version is exactly the same as the regular version.

Browser support

The TTI polyfill will work in any browser that supports PerformanceObserver and the PerformanceLongTaskTiming entry.

At the moment this is Chrome 58+.