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

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Serve a single-page app

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](/object-storage) bucket and create a
   distribution that reads it: see [Serve a private bucket](/cdn/guides/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:

   ```sh
   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:

   ```sh
   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](https://github.com/google/re2/wiki/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:

```sh
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](/cdn-api/UpdateDistribution/)):

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

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

Source: https://docs.ezghcloud.com/cdn/guides/serve-a-single-page-app/index.mdx
