Menu Sheet Overlay

Mobify Progressive Web SDK Docs

UPWA Fundamentals

A UPWA is a Universal PWA. The "Universal" part means that it runs across many devices: phones, tablets and desktops.

The Mobify Platform supports building UPWAs using the same components and developer workflow used for PWAs. UPWAs are built using React to render HTML, and Redux to store application state.

We'll assume that you're familiar with how PWAs work on the Mobify Platform:

  • The PWA renders HTML using React components
  • The HTML rendered depends on the route (the path of the URL for the page that's shown in the browser)
  • Data is pulled from a backend server (sometimes a webserver that returns HTML, sometimes an ecommerce backend that provides a REST API)

However, there are some fundamental concepts that are new to UPWAs. To explain these concepts, we'll use this scenario:

  • WidgetCorp, Inc is developing a new UPWA for their existing website,
  • They have an ecommerce backend, which is available at, from which the UPWA will take data to render the pages.

The SDK documentation also contains a reference section on UPWAs.

Server-side Rendering

Server-side rendering (usually abbreviated to SSR) uses the UPWA code to generate the HTML returned by a server to a client.

Currently, WidgetCorp runs a webserver, and the hostname points to that webserver. When a device requests a URL from the webserver, the webserver fetches data from the backend server, uses it to render an HTML page for that URL and returns the page to the device.

When the UPWA is launched, will point instead to an SSR server (code that runs on the Mobify Platform). When a device requests a URL from the SSR Server, it will do the following:

  1. Run the UPWA code, setting the route to match the URL
  2. Allow the UPWA to render HTML, using React, with state kept in the Redux store. The UPWA is able to fetch data from the backend server.
  3. Once rendering is complete, return an HTML page to the device that contains:
    • The HTML that the UPWA rendered
    • A copy of the state from the Redux store
    • A <script> element that will load the UPWA on the browser

When the page is received by the device, it can immediately display the HTML while the UPWA loads, which allows a fast startup (faster than a PWA).

An important point to note is that the UPWA is run in two different places:

  • Server-side, in the SSR Server
  • Client-side, in the browser

This is part of the UPWA Lifecycle, which is explained below (and in more detail in the reference documentation).


The WidgetCorp website contains assets (scripts or other files) and handles POST requests that the UPWA will use when rendering. As an example, we'll consider the following:

  • is the corporate logo image. The UPWA will need to use this image in rendered HTML.

  • is a analytics script that provides tracking of browser usage. The UPWA-rendered pages should load this script.

  • is a URL that the web server provides, which handles checking of credentials sent in a POST, and sets a login cookie in the response. The response also contains CORS headers to restrict access.

When the UPWA is launched, will no longer point at the WidgetCorp webserver, and so these URLs will no longer work. To fix this, the UPWA can use the proxying support built into the Mobify Platform.

Here's how we can set that up:

  1. Add a new hostname that will continue to point to the WidgetsCorp webserver even when changes to point to the SSR Server. We call the target hostname for proxying.
  2. Configure proxying so that requests to will be automatically forwarded to the server. We call the application hostname for proxying.

Once this is set up, a request for will be routed to The UPWA can then render Image components that use the /mobify/proxy/base path, and the images will be fetched from the WidgetCorp webserver.

Similarly, to load the script, the UPWA would use the path

Finally, the UPWA can use the /login URL via a POST to The request and response are processed so that headers such as Host and Access-Control-Allow-Origin are modified, to allow use of the URL despite the POST being made to instead of

Proxying has a number of advantages:

  • It's fully transparent and rewrites the request and response so that POSTs, PUTs and GETs work via the proxy.
  • The browser can make all requests to (the application hostname), avoiding CORS issues.
  • It supports multiple proxy setups, so more than one target host can be proxied (each has a separate path under /mobify/proxy)
  • Because the proxying paths are available on the application hostname, browsers can re-use existing connections to that hostname, resulting in improved performance.

Proxying is described in more detail here.

Bundle Assets

UPWAs using the Mobify Platform, like PWAs, are made up of files that are deployed as part of a code bundle. The SSR Server makes bundle files available under the path /mobify/bundle/. Each bundle has a bundle id (a number unique within the project), and the full path used to refer to bundle files is /mobify/bundle/<bundle-id>/ (when running the local development SSR server, the path will be /mobify/bundle/development/). These paths are relative to whatever hostname is being used to address the SSR server.

When a new bundle is deployed, browsers that load the new version of the UPWA will use the correct path for assets within that new bundle, while existing versions of the UPWA will use the correct paths for files in their bundles.

Because the bundle files are loaded via a path on the application hostname, browsers can re-use existing connections to that hostname, resulting in improved performance.

The UPWA Lifecycle #

There is a key difference between UPWAs and PWAs. UPWAs run on the SSR server and then again in the browser. PWAs only ever run and render in the browser.

When a UPWA is running on the SSR server, we say that it is running server-side. When a UPWA is running in the browser, we say that it is running client-side (the browser is the "client").

A UPWA therefore has several stages of execution, and we use the term UPWA Lifecycle to refer to these.

The lifecycle can be summarized:

  1. A device makes a request to the SSR server for a page
  2. The SSR server runs the UPWA code server-side to generate the HTML
  3. The HTML is returned to the device which displays it
  4. The device then loads the UPWA code into the browser
  5. The UPWA starts up and "hydrates") by rendering the same HTML that was sent from the server, so that React now owns that HTML
  6. The UPWA completes hydration and runs client-side. The user can now navigate to other pages, which are rendered by the UPWA running client-side.

The full lifecycle, including an explanation of how UPWA code can identify the lifecycle stages, plus what should and should not be rendered in each stage, is explained in detail here.


Was this page helpful?