Edit this page

up.network up.network.config
JavaScript property

Sets default options for this package.


[config.concurrency=4] number optional

The maximum number of concurrently loading requests.

Additional requests are queued. Preload requests are always queued behind non-preload requests.

You might find it useful to set the request concurrency 1 in end-to-end tests to prevent race conditions.

Note that your browser might impose its own request limit regardless of what you configure here.

[config.wrapMethod] boolean optional

Whether to wrap non-standard HTTP methods in a POST request.

If this is set, methods other than GET and POST will be converted to a POST request and carry their original method as a _method parameter. This is to prevent unexpected redirect behavior.

If you disable method wrapping, make sure that your server always redirects with with a 303 status code (rather than 302).

[config.cacheSize=70] number optional

The maximum number of responses to cache.

If the size is exceeded, the oldest responses will be dropped from the cache.

[config.cacheExpiry=300000] number optional

The number of milliseconds until a cached response expires.

Defaults to 5 minutes.

[config.badRTT=0.6] number optional

The connection's maximum effective round-trip time required to prevent Unpoly from reducing requests.

The value is given in milliseconds. Lower is better.

[config.badResponseTime=400] number optional

How long the proxy waits until emitting the up:request:late event.

Requests exceeding this response time will also cause a progress bar to appear at the top edge of the screen.

This metric is not considered for the decision to reduce requests.

The value is given in milliseconds.

[config.autoCache] Function(up.Request): boolean optional

Whether to cache the given request with { cache: 'auto' }.

By default Unpoly will auto-cache requests with safe HTTP methods.

config.clearCache Function(up.Request, up.Response)

Whether to clear the cache after the given request and response. By default Unpoly will clear the entire cache after a request with an unsafe HTTP method.

[config.requestMetaKeys] Array<string>orFunction(up.Request): Array<string> optional

An array of request property names that are sent to the server as HTTP headers.

The server may return an optimized response based on these properties, e.g. by omitting a navigation bar that is not targeted.

Cacheability considerations

Two requests with different requestMetaKeys are considered cache misses when caching and preloading. To improve cacheability, you may set up.network.config.requestMetaKeys to a shorter list of property keys.

Available fields

The default configuration is ['target', 'failTarget', 'mode', 'failMode', 'context', 'failContext']. This means the following properties are sent to the server:

Request property Request header
up.Request#target X-Up-Target
up.Request#failTarget X-Up-Fail-Target
up.Request#context X-Up-Context
up.Request#failContext X-Up-Fail-Context
up.Request#mode X-Up-Mode
up.Request#failMode X-Up-Fail-Mode

Per-route configuration

You may also configure a function that accepts an up.Request and returns an array of request property names that are sent to the server.

With this you may send different request properties for different URLs:

up.network.config.requestMetaKeys = function(request) {
  if (request.url == '/search') {
    // The server optimizes responses on the /search route.
    return ['target', 'failTarget']
  } else {
    // The server doesn't optimize any other route,
    // so configure maximum cacheability.
    return []
[config.progressBar] booleanorFunction(): boolean optional

Whether to show a progress bar for late requests.

The progress bar is implemented as a single <up-progress-bar> element. Unpoly will automatically insert and remove this element as requests are late or recovered.

The default appearance is a simple blue bar at the top edge of the screen. You may customize the style using CSS:

up-progress-bar {
  background-color: red;
This website uses cookies to improve usability and analyze traffic.
I accept or learn more