beforeunload-request

A unified API to reliably send data on beforeunload.

Why

There is often a need to send data to a server before a page is closed. Asynchronous XHR requests aren't guaranteed to be sent in such a scenario, so traditionally developers have used synchronous XHR requests. However, due to the poor user experience that synchronous XHR requests on beforeunload cause, browsers have started disallowing them. There are alternatives to synchronous XHR (navigator.sendBeacon and fetch with keepalive), but these new APIs have their own set of quirks and browser issues.

This library unifies all available methods into a single API that prevents common pitfalls (see Methodology).

Installation

$ npm install beforeunload-request

Usage

import beforeunloadRequest from 'beforeunload-request';

const success = beforeunloadRequest(url, options);

Parameters

| Option | Description | Default | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | url | URL to send request to (required). | | | options | RequestInit object. The entire object is passed to fetch, however, only the options listed below are considered for sendBeacon and XMLHttpRequest. | | | options.method | HTTP method to use. | 'POST' | | options.headers | Object of HTTP headers to use. | null | | options.body | A string or BodyInit type for the data to send. No automatic conversion of any kind is done (e.g. you must convert to JSON or to URL encoded values yourself). | null | | options.credentials | A RequestCredentials string for the credentials mode to use. | 'include' |

Return value

The function returns a boolean indicating if the request was successful, with one important caveat: if fetch is used, it will always return true; it's impossible to synchronously know if a fetch will result in an error. Otherwise, false guarantees the request did not go through.

Examples

Simple POST request

beforeunloadRequest('/flushSession');

PUT with JSON

beforeunloadRequest('/save', {
	method: 'PUT',
	body: JSON.stringify(data),
	headers: {
		'Content-Type': 'application/json'
	}
});

Using the return value

window.addEventListener('beforeunload', event => {
	const success = beforeunloadRequest('/save', {
		method: 'PUT',
		body: JSON.stringify(data),
		headers: {
			'Content-Type': 'application/json'
		}
	});

	if (!success) {
		// Show a warning that the user might lose data if they leave the page
		event.preventDefault();
		event.returnValue = '';
	}
});

Browser compatability

This library requires, at the minimum, support for XMLHttpRequest, including setRequestHeaders and withCredentials. Those are supported in IE10 and above.

Methodoloy

We first try to use navigator.sendBeacon if it's available and the request is compatible. Compatible requests are POST requests with 'include' as the credentials mode and no headers, with the exception of Content-Type if the data being sent is a string. navigator.sendBeacon can also fail if the data being sent is over the maximum size limit or due to a browser issue with Content-Type.

If navigator.sendBeacon is not available, if the request is not compatible, or if it otherwise fails, we then try to use synchronous XMLHttpRequest. Some browsers disallow synchronous XHR on beforeunload.

If synchronous XHR fails, we try fetch with the keepalive flag set. We do this after synchronous XHR because fetch with keepalive can fail in certain situations due to a browser issue with headers. This failure cannot be intercepted in a synchronous manner, so there is no way to recover with a different method.

This execution order ensures cross-browser compatability with, despite the quirks and issues with the new APIs. That being said, to guarantee the best user experience, you should aim for your requests to be compatible with navigator.sendBeacon. This avoids users having to wait for the synchronous XHR to complete when attempting to navigate away.