Deploy frontend applications

A front-end team builds the web interface of a product whose backend already runs elsewhere, in a cloud region, a data center, or a SaaS API. The interface is a single-page application built with a framework such as React, Vue, or Angular, and the backend stays where it is. This page serves the compiled interface from Azion, falls back to the entry HTML for client-side routes, and sends every request under /api/ through a connector to the existing backend, on the same domain. The result is measured by interface load time per region, the time from a commit to a live change, and the latency the routing adds to API calls.

This use case does not cover applications whose backend also runs on Azion. For that, refer to Deploy full-stack applications globally.

Prerequisites

• A single-page application deployed to Azion with the Azion CLI and its framework preset, from a project folder that holds its azion.config.cjs file. The deploy creates the bucket, the application, and the workload that serve the interface. For the React route, refer to Build with React. Vue and Angular follow the same route with their own preset.
• The Azion CLI, installed and logged in, in that project folder.
• A backend that answers HTTPS on port 443 under its own hostname.
• The values of your interface. This page uses api.example.com for the backend, /api/ for the path prefix of every API call the interface makes, /api/health for one backend path the checks request, and <workload-domain> for the domain the deploy printed. Replace each value with yours in every step.

Required products

Reference architecture

This page builds the Client-rendered frontend over origin APIs: the browser renders the interface from static files, and every data call crosses Azion to the existing backend.

The diagram carries two flows. The publish flow runs from the repository to the bucket, and it moves only when the team deploys a change. The request flow starts at the browser, and the application’s rules split it three ways: API paths cross to the backend, files of the build come from Cache or the bucket, and every client-side route returns the entry HTML. Only the first path leaves Azion, so a page load reads static files, and every data call reaches the backend origin.

Dataflow

1. A push to the repository, or azion deploy from the project folder, builds the interface and uploads the build output to the bucket.
2. A browser’s request reaches the workload on the interface’s domain, and the application runs its request rules in order.
3. A request under /api/ matches the first rule, which sends it through the backend connector and ends the request phase, so no later rule rewrites or caches it.
4. The backend answers the API call, and the browser renders the data into the interface.
5. A request for a file of the build, such as a script or a stylesheet, is answered from Cache. On a miss, the application reads the file from the bucket and caches it.
6. A request for a client-side route, such as /orders/42, is rewritten to /index.html, and the router in the browser renders that route.

Components

• Object Storage: holds the compiled interface in a bucket that workloads can only read. The interface has no server of its own, so the bucket is its origin.
• Cache: keeps the files of the build near the browsers that request them, so repeated page loads read the files from Cache instead of the bucket.
• application: the Platform Resource that serves the interface’s domain and holds the rules that split files, routes, and API calls.
• Rules Engine: the Feature of the application that routes API paths to the connector and rewrites client-side routes to the entry HTML. The API rule runs first and ends the Request Phase, because every matching rule runs in order and a later rule could rewrite an API call.
• connector: the Platform Resource that reaches the backend. It sends the backend’s own name in the Host header, so a backend that serves several sites answers for it.
• backend API: the integration that is the existing origin. It stays where it runs, and every data call of the interface reaches it.
• Azion GitHub App: the integration that imports the repository and deploys every push to it, so the interface on Azion follows the repository.

Other designs for this use case

• Server-rendered frontend over origin APIs: for interfaces that need server rendering, such as search-indexed or personalized pages. Functions render each page on request with a framework such as Next.js or Nuxt and call the backend’s APIs, so the backend sits in the request flow and the failure flow of every page that Cache does not hold.

Configure the API route

The API route is a connector to the backend and a rule that sends every /api/ request to it. Both go in the project’s azion.config.cjs, the file that azion deploy applies to the application, so the route ships with every deploy of the interface.

The rule is the first entry of the request rules, and it ends the request phase. The preset’s Redirect to index.html rule rewrites route requests to /index.html, and every matching rule of the phase runs, in order. Without a stop, a later rule could rewrite an API call’s path or apply the cache setting of the interface files to it. Finish Request Phase ends the phase, so the rules after it never see an API call.

The project’s azion.config.cjs declares the route as Route an API path to a backend from azion.config describes, with these values, and azion deploy in the project folder applies it:

Requests under /api/ reach api.example.com with their own path, and every other request keeps the preset’s behavior. A new rule takes a few minutes to reach every data center.

Verify the setup

• The interface loads. Request the root of the domain:

  curl -s -D - -o /dev/null https://<workload-domain>/

  The response carries 200. Until the deploy reaches a location, the domain answers 404 with a page that reads There's nothing here yet. Wait and request it again.

• A client-side route loads the interface. Request a route the interface handles, such as /orders/42:

  curl -s https://<workload-domain>/orders/42

  The body is the same entry HTML that / returns. The router in the browser then renders the route.

• Interface files come from cache. Request a script of the build twice, with the debug header. Take its path from a <script> tag of the entry HTML:

  curl -sI -H "Pragma: azion-debug-cache" https://<workload-domain>/<script-path>

  The second response carries x-cache: HIT. For how to read the header, refer to Check the cache status of a response.

• API calls reach the backend. Request a backend path:

  curl -s -D - https://<workload-domain>/api/health

  The response is the backend’s own answer for /api/health, not the entry HTML. When it is the entry HTML, the API rule is not the first request rule, or it has not propagated yet.

To see which rules ran on a request, turn on Debug Rules.

Measuring results

Best practices

• Call the API with relative paths. An interface that calls /api/orders reaches the backend through the same domain that served it, so the backend’s hostname appears only in the connector, and moving the backend changes one connector instead of the interface code.
• Keep the API rule first, and end the request phase in it. A later rule can still rewrite or cache what an earlier rule routed, because every matching rule runs. Finish Request Phase is what keeps the rewrite and the interface cache off the API path. For how rules run in order, refer to How Applications works.
• Declare the route in the configuration file. azion deploy applies the rules the file declares to the application. A rule kept in one place goes out with every deploy of the interface.
• Send the backend’s own name in the Host header. A backend that serves several sites picks the site by Host. For when to send ${host} and when a literal name, refer to Set the Host header to a name your origin answers for.

Guides in this use case