If you're using Azure Static Web Apps to host a Single Page Application (SPA) (such as React, Angular, or Vue), you might have encountered a 404 error or a blank screen when refreshing the page or directly accessing a deep link. This issue occurs because SPAs rely on client-side routing, while Azure Static Web Apps, by default, expect a physical file to serve for each route. In this article, we'll explore why this happens and how to fix it.

Why Does This Issue Occur?

Unlike traditional server-side applications, SPAs use client-side routing to navigate between pages without reloading. However, when a user refreshes the browser or accesses a deep link like /dashboard, the browser sends a request to the server for /dashboard. Since there is no actual file named /dashboard.html, Azure Static Web Apps responds with a 404 Not Found error.

This is a common issue in cloud hosting platforms when serving SPAs, but Azure provides a simple way to fix it.

Solution:

To fix this issue we need to correctly serve the index.html file for all unknown routes (allowing the frontend framework to handle them).

In Azure Static Web Apps, this is done by defining a navigation fallback (navigationFallback) in staticwebapp.config.json

staticwebapp.config.json

The recommended location for staticwebapp.config.json is inside the folder set as app_location in your workflow file. If a build process is involved, the best approach is to ensure that this file is included in the output directory (output_location).
Essentially, it should be part of the files copied to Static Web Apps.

app_location: Often the root of the code (/).

output_location: Typically the build or dist folder.

Documentation: File location | Configure Azure Static Web Apps | Microsoft Learn

If it doesn’t exist, create one and add the following configuration:


{ 
  "navigationFallback": { 
    "rewrite": "/index.html", 
    "exclude": ["/assets/*", "/static/*", "/images/*"] 
  } 
}

Deploy the Changes

Commit and push your changes to your Azure Static Web Apps repository. Once deployed, your app should correctly handle deep links and refreshes without 404 errors or blank pages.

How This Works

The navigationFallback rule tells Azure to serve index.html for any route that does not map to a physical file. This allows the SPA's router (React Router, Vue Router, Angular Router, etc.) to handle the request and display the correct page.

The exclude array ensures that static assets (like images, CSS, and JS files) are not mistakenly redirected to index.html. Make necessary adjustments according to your requirements.

"exclude": ["/*.{png,jpg,gif}"]

Prevents rewriting image files (PNG, JPG, GIF) in the root directory, ensuring they are served normally instead of redirecting to index.html.

"exclude": ["/assets/*", "/static/*", "/images/*"]

Excludes entire directories (/assets/, /static/, /images/) from being rewritten, so all files inside these folders load as static resources.

Alternative: Hash-Based Routing - Not Recommended

If you don’t want to modify Azure settings, an alternative solution is to use hash-based routing. This ensures that URLs always include a # (e.g., /#/dashboard instead of /dashboard). Since everything after # is handled by client-side routing , the server does not attempt to resolve the route.

While this approach works, it results in complex URLs and is not as SEO-friendly .

Conclusion

By configuring staticwebapp.config.json, you can prevent 404 errors and blank screens when reloading or accessing deep links in Azure Static Web Apps. This small change ensures that your SPA works seamlessly, improving user experience.

For official documentation, refer to: Configure Azure Static Web Apps | Microsoft Learn

If you have any questions, feel free to comment below!

Amal Shibu

Amal's Blogposts