This is the legacy documentation of Project-level Custom Applications, which is in maintenance mode. Visit the new documentation for Org-level Custom Applications.

Serving Static Assets

After building the production bundles you need to think about deploying and hosting your Custom Application. A Custom Application is a Single-Page Application (SPA) and thus is composed by a bunch of static files such as HTML, JS, CSS.

Deploying the Custom Application to a production environment means to be able to serve the static files, in particular the compiled index.html. This primarily depends on the hosting provider and how it serves static files.

In general we recommend to serve JS and CSS static files from a remote Content Delivery Network (CDN) or Cloud Storage if possible.

Serving assets from a remote CDN or Cloud Storage

This is usually the recommended approach. It prevents broken references. A broken reference is when a file is requested by the browser which is no longer found on the server. It often happens during application re-deploys.

For example, imagine if a user has the Merchant Center opened in the browser. The index.html page contains references to the static assets, for example, app.v1.js. If we have the static assets served by the HTTP server, when a new version of the application is deployed, the app.v1.js file is no longer present on the HTTP server. If the user performs an action without reloading the browser, there is a chance that the app.v1.js file is requested by the browser, is unavailable, and causes a runtime error.

If the static assets are uploaded to a remote CDN or Cloud Storage instead, uploading new versions of the application doesn't affect old versions that might still receive outdated assets. When a user reloads the page, the browser requests the new assets, and the application starts seamlessly.

To configure the Custom Application to serve static assets from a remote CDN or Cloud Storage, you need to specify the CDN URL in the env.production.cdnUrl in the application config.

custom-application-config.jsonjson

{
  "env": {
    "production": {
      "cdnUrl": "https://cdn.my-app.com"
    }
  }
}

Serving assets from the same location

In this scenario, static assets are served within the same domain location where the compiled index.html of the Custom Application is hosted. This is generally less recommended but it also depends on how the hosting provider handles and serves the static assets. For example, Vercel has a Content Delivery Network built-in that does not require to deploy the application and its static files separately.