How to Deploy a Single Page App on Netlify (and Fix Routing Bugs)

Deployment Issue with SPAs on Netlify

When deploying a Single Page Application (SPA) on Netlify, everything may seem fine at first. The app builds and loads correctly, but issues appear when navigating directly to a route or refreshing the page. Instead of loading the page, Netlify returns a 404 error.

This happens because SPAs rely on client-side routing, while Netlify expects actual files for each URL path.

Why It Breaks

Unlike traditional multi-page websites, SPAs handle routing in the browser. So routes like /about or /profile don’t exist as real files on the server. When Netlify tries to access them directly, it fails to find a matching file and throws an error.

The Fix (Two Ways to Handle Routing)

To solve this, we need to make sure Netlify always serves the main entry file (index.html) for every route. This allows the frontend router to handle navigation instead of Netlify trying to find real files for each path.

There are two common ways to fix this:

1. Using _redirects File

This is the simplest method. You create a file called _redirects inside the public folder and add the following rule:

/*    /index.html   200

This tells Netlify to redirect all routes to your main entry file while keeping the response successful.

2. Using netlify.toml Configuration

Another approach is to define the redirect rule inside a netlify.toml file. This is cleaner for larger projects and keeps configuration in one place.

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 20

Both methods achieve the same result — ensuring your SPA routing works correctly after deployment on Netlify.

What This Does

This rule ensures that no matter what URL is accessed, Netlify always loads the app entry point. After that, the SPA framework (Vue, React, etc.) handles routing internally, making navigation smooth and error-free.

Result

Once this is added, refreshing pages and direct URL access works normally. The app behaves like a multi-page website but still runs as a single-page application under the hood.

Final Note

This small configuration is essential for any SPA deployment on Netlify. Without it, routing will break — with it, the deployment becomes stable and production-ready.