Navigation

Host a Single-Page Application

On this page

Overview

Many web applications built with modern frameworks, like React, Vue, and Angular, are single-page applications (SPAs) that dynamically handle routing and rendering client-side instead of fetching each rendered page from the server. You can use MongoDB Realm to host your SPA and serve it to clients.

To host your app, you need to specify that it’s a SPA in Realm. By default, Realm handles requests for a given resource by returning the file hosted at the specified resource path or a 404 if no file matches the path. However, SPAs render in a single, specific HTML file so all requests should return that file regardless of the requested resource path.

This guide covers how you can configure Realm Hosting to redirect all resource requests to a single file to support the SPA pattern.

404 Errors in Single-Page Apps

When single-page application hosting is enabled, Realm always returns an HTTP 200 response with the app root regardless of the requested route. This means that you cannot specify a custom 404 page for a SPA. Instead, you should include custom code in your application to handle invalid routes.

Procedure

1

Upload Your Built Application to Realm

Single-page applications render in a single, specific HTML file, typically /index.html. The file should include the necessary JavaScript code to wire up and render your application, either inline in a <script> tag or imported from an external file. You’ll also need to host any resources that you don’t intend to access through a CDN.

When you are ready to host your SPA, run your application’s build script and then upload the build folder to MongoDB Realm.

2

Configure Realm to Serve Your Application

Once you’ve started hosting your application files, you can immediately access your SPA by requesting the root HTML file directly. However, a request to any path other than the root file will return a 404. This can break the expected behavior of a SPA that uses a client-side router or otherwise relies on the URL path.

To configure Realm to serve the SPA’s root page for all requests:

  1. Navigate to the Hosting page in the Realm UI and then click the Settings tab.
  2. Ensure that you have not specified a custom 404 page. If custom 404 is enabled, click the trash can icon ( trash icon ) next to the specified 404 page.
  3. Next to Single Page Application, click Choose File. Choose the root HTML file for your SPA and then click Select.
  4. Click Save.
../../_images/enable-spa-realm-ui.png
1

Get a Local Copy of Your Realm App

To use code deploy to configure a SPA, you need a local copy of your application directory that is up-to-date with the latest version of your Realm app. Clone the most recent version of your Realm app from GitHub or export it directly from MongoDB Realm.

Export Your Application

You can export a copy of the latest version of your application directory from the Import/Export App tab of the Deploy page in the Realm UI, or by running the following command from an authenticated instance of realm-cli:

realm-cli export --app-id=<App ID>
2

Add Your Built Application Code

Single-page applications render in a single, specific HTML file, typically /index.html. The file should include the necessary JavaScript code to wire up and render your application, either inline in a <script> tag or imported from an external file. You’ll also need to host any resources that you don’t intend to access through a CDN.

When you are ready to host your SPA, run your application’s build script and then copy the output build folder into the /hosting/files directory of your application directory.

3

Configure Realm to Serve Your Application

In config.json, set the value of hosting.default_response_code to 200 and set the value of hosting.default_error_path to the resource path of your SPA’s root HTML file. Make sure to save the file when you’re done.

config.json
"hosting": {
  "enabled": true,
  "default_response_code": 200,
  "default_error_path": "/index.html",
}
4

Deploy Your Changes

Now that you’ve added the SPA code to the hosting/files directory and configured Realm to serve the root HTML file, all that’s left is to deploy the changes.

Navigate to the application directory root and then run the command that matches your deployment method.

If you want to deploy with Realm CLI:

realm-cli import --include-hosting

If you want to deploy automatically with GitHub:

git add -A
git commit -m "<descriptive commit message>"
git push <github remote> <branch>