Host a Single-Page Application
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 Atlas App Services to host your SPA and serve it to clients.
To host your app, you need to specify that it's a SPA in App Services. By default, App Services 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 App Services Hosting to redirect all resource requests to a single file to support the SPA pattern.
Note
404 Errors in Single-Page Apps
When single-page application hosting is enabled, App Services 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
Upload Your Built Application to App Services
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 App Services.
Configure App Services 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 App Services to serve the SPA's root page for all requests:
Navigate to the Hosting page in the App Services UI and then click the Settings tab.
Ensure that you have not specified a custom 404 page. If custom 404 is enabled, click the trash can icon () next to the specified 404 page.
Next to Single Page Application, click Choose File. Choose the root HTML file for your SPA and then click Select.
Click Save.
Note
Enable hosting in the UI
Before you start using the App Services CLI with Static Hosting, you must enable hosting in the App Services UI.
Pull the Latest Version of Your App
To configure a single-page application with the App Services CLI, you need a local copy of your application's configuration files.
To pull a local copy of the latest version of your app, run the following:
appservices pull --remote="<Your App ID>"
Tip
You can also download a copy of your application's configuration files from the Deploy > Import/Export App screen in the App Services UI.
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.
Configure App Services to Serve Your Application
In hosting/config.json, set default_response_code to 200 and set
default_error_path to the resource path of
your SPA's root HTML file. Make sure to save the file when you're done.
{ "enabled": true, "default_response_code": 200, "default_error_path": "/index.html", }