Menu Sheet Overlay

Mobify Progressive Web SDK Docs

UPWA Proxying

Proxy Configuration #

Proxying is configured by properties of the mobify object at the top level of the project's package.json file. For example:

  "name": "widgetcorp-progressive",
  "mobify": {
    "pageNotFoundURL": "/page-not-found",
    "ssrEnabled": true,
    "ssrParameters": {
      "proxyConfigs": [
          "protocol": "https",
          "host": "",
          "path": "base"
          "protocol": "https",
          "host": "",
          "path": "base2"

This example configures two proxies:

  • Requests to /mobify/proxy/base will be proxied to
  • Requests to /mobify/proxy/base2 will be proxied to

The /base and /base2 paths are defaults; they're shown in the example above for clarity, but can be omitted. The proxyProtocol can be https or http (Mobify recommend use of https).

A host to which requests are proxied is referred to as a target host. The configuration in package.json is set for the UPWA project. However, to support use of test environments using a test target host, any target in Mobify Cloud can be configured to override the protocol and/or host for one or both proxies (contact Mobify to request this).

Standard And Caching Proxying

The paths in the examples above start with /mobify/proxy/. Requests made via these paths are handled using standard proxying. This passes cookies and all the standard HTTP request headers to the target host, and supports GET, POST, PUT and other HTTP methods. This provides full access to the target host, but the responses are generally not cacheable, since they may depend on cookie values, which often differ between requests.

It's also possible to make requests to the target host using paths that start with /mobify/caching/. In the example above:

  • Requests to /mobify/caching/base will be proxied to
  • Requests to /mobify/caching/base2 will be proxied to

These requests will be handled using caching proxying. In contrast to standard proxying, caching proxying:

  • Does not send cookies, and ignores cookies when caching responses
  • Ignores all but a subset of headers when caching responses
  • Removes all Set-Cookie headers from responses

This means that the responses are much more likely to be cacheable. In general, you use standard proxying where the presence of cookies matters (e.g. where they are required for the server to generate a response) and caching proxying where cookies don't affect the response (e.g. when requesting a fixed asset like an image, stylesheet or font).

Overriding Proxy Configuration

When using the local development SSR server, it's also possible to override the configuration of any configured proxy, using environment variables SSR_PROXY1 for the first proxy, SSR_PROXY2 for the second proxy and so on. The value of the variable should be an origin in the form <protocol>://<hostname followed by the path, optionally followed by /caching for a caching proxy. For example:


You can currently configure up to 2 proxies.

Proxy Behaviour

Proxying will affect the headers of a proxied request and its response. In this section, we assume that the SSR server is available at (referred to as the application hostname in proxying).


  • The Host header is rewritten to contain the target hostname. For example, with the above example, a request to would have the Host header rewritten from to
  • The path of the request is rewritten to remove the /mobify/proxy/base prefix. For example, a request to would have the path rewritten to /logo.png
  • A new x-mobify header is added with value true, so that it's clear a request was proxied through Mobify infrastructure


  • The response will include an X-Request-Url header whose value will be the URL sent to the target host. This can be useful in detecting redirects, since not all browsers provide support for handling redirects, even with a fetch polyfill. This will always be a URL on the target host - it won't contain the /mobify/proxy/... part of the URL.
  • If the response is a redirect (status code in the range 301 to 307) and the response's Location header is a relative path or a path on the target hostname, then it's rewritten to be the correct path on the application hostname. For example, a response that redirects to /otherpath/logo.png would be rewritten to /mobify/proxy/base/otherpath.png. This allows a browser to follow the redirect.
  • If the response contains any Set-Cookie headers that have domain values referring to the target hostname, they are rewritten to use the application hostname. For example, Set-Cookie: abc=123; would be rewritten as Set-Cookie: abc=123;
  • If the response contains an Access-Control-Allow-Origin header that restricts access to the target hostname, that header is rewritten to use the application hostname. For example, Access-Control-Allow-Origin: would be rewritten as Access-Control-Allow-Origin:

Proxying supports the standard HTTP methods:

  • HEAD
  • POST
  • GET
  • PUT

Proxied requests have all query parameters, headers and cookies forwarded.

Proxy utility functions

UPWA code can get access to the currently configured set of proxies using the getProxyConfigs function. This returns the set of proxies configured for a UPWA. The result is an Array of objects, each of which has the following properties:

  • protocol - either 'http' or 'https',
  • host - the hostname,
  • path - the path element that follows /mobify/proxy/, defaulting to base for the first proxy, and base2 for the second.

Proxy 1 is always the first entry in the Array. If proxy 2 is configured, it's the second entry.


Was this page helpful?