Skip to content

Serve a single-page app

Serve a React, Vue or other single-page app from a distribution, with rewrites that answer its client-side routes with index.html.

Updated View as Markdown

A single-page app is one index.html and its assets, and the app’s router handles paths such as /dashboard/settings in the browser. A distribution’s rewrites send those paths to the origin as /index.html, so opening or reloading any route loads the app.

  1. Upload the app’s build output to an Object Storage bucket and create a distribution that reads it: see Serve a private bucket. Any other origin works the same way.

  2. Add the rewrite. In the console, open the distribution, select Edit rewrites, then Single-page app. With the CLI:

    ezgh cdn distributions update cdn_k2m9x0a7qpe4 --rewrite '^/[^.]*$=/index.html'

    Every path without a dot, / included, is now answered with index.html. Paths with a dot, such as /assets/app.js, go to the origin as they are.

  3. Wait for the distribution’s status to be deployed, then open a route:

    curl https://d4k2m9x0a7qpe.ezghcdn.com/dashboard/settings

How rewrites work

A rewrite is a pattern and a replacement. A request whose path matches the pattern is sent to the origin with the replacement as its path.

  • A distribution has up to 10 rewrites, tried in order. The first match wins, and a path that matches none is sent as it is.
  • pattern is a regular expression in RE2 syntax, at most 256 characters. It matches anywhere in the path unless anchored with ^ and $.
  • replacement is the whole new path. It starts with /, is at most 256 characters, and can use the pattern’s capture groups as $1, $2.
  • Only the path is matched, without the query string. The query string is sent to the origin unchanged.
  • The visitor’s URL doesn’t change: a rewrite isn’t a redirect.
  • The origin’s status code is returned as it is. An unknown route answers 200 with index.html.
Pattern Replacement Effect
^/[^.]*$ /index.html Paths without a dot load the app
^/docs/[^.]*$ /docs/index.html The same for an app under /docs
^/old/(.*)$ /new/$1 /old/a.png reads /new/a.png

A route with a dot in it, such as /users/jane.doe, doesn’t match ^/[^.]*$. Put a rule for it first:

ezgh cdn distributions update cdn_k2m9x0a7qpe4 \
  --rewrite '^/users/=/index.html' \
  --rewrite '^/[^.]*$=/index.html'

--rewrite replaces the list, and --clear-rewrites removes it.

With the API

Create or replace the distribution with rewrites (UpdateDistribution):

{
  "name": "app",
  "origin": { "bucket": "acme-app" },
  "rewrites": [{ "pattern": "^/[^.]*$", "replacement": "/index.html" }]
}

A replace is the whole document: left out, the distribution has no rewrites.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close