Introduction

A catch-all route for index.html is a common Spring Boot pattern when you serve a single-page application from the same backend. The goal is to let real API routes and static assets behave normally while forwarding unknown browser paths such as /profile or /settings/account to the SPA entry page so the client-side router can take over.

Why You Need It

A browser refresh on an SPA route sends a real HTTP request to the server. If Spring does not know about that path, it returns 404 even though the front-end router would have handled it correctly after index.html loaded.

The fix is to forward non-API, non-static paths to index.html.

That means the backend should:

• keep API endpoints such as /api/... mapped normally
• keep static files such as .js, .css, and images served normally
• forward everything else intended for the front-end router

A Simple Controller-Based Solution

A common Spring MVC solution is to forward routes that do not contain a dot and are not part of the API namespace.

1import org.springframework.stereotype.Controller;
2import org.springframework.web.bind.annotation.GetMapping;
3
4@Controller
5public class SpaForwardController {
6
7    @GetMapping(value = {
8        "/{path:[^.]*}",
9        "/**/{path:[^.]*}"
10    })
11    public String forward() {
12        return "forward:/index.html";
13    }
14}

This works because real static assets usually contain a file extension such as .js or .css, while client-side routes usually do not.

Protect Your API Routes

You usually do not want /api/users forwarded to index.html, because that hides actual backend routing mistakes.

A simple strategy is to put APIs under a dedicated prefix such as /api and make sure your catch-all controller does not overlap with that namespace.

In many applications, route naming discipline matters more than clever regex.

Project Layout Matters Too

For Spring Boot to serve the SPA entry page automatically, index.html is usually placed under a static resource directory such as:

src/main/resources/static/index.html

If the file is not located where Spring expects static resources, forwarding to /index.html will not resolve correctly.

When a Catch-All Is Not the Best Fit

If the SPA is served by a dedicated front-end server or CDN and Spring only exposes APIs, then Spring does not need a catch-all route at all. In that architecture, the front-end host handles SPA routing and the backend stays purely API-focused.

So before adding a catch-all controller, confirm that Spring is actually responsible for serving the front-end assets.

Testing the Behavior

A good sanity check is:

• open / and confirm the SPA loads
• refresh a deep client route such as /dashboard
• confirm /api/... still reaches controllers rather than loading HTML
• confirm missing assets still produce a real missing-file response rather than returning index.html

That last point matters because accidentally forwarding asset requests can make debugging much harder.

Common Pitfalls

Forwarding every unknown path indiscriminately can hide backend routing errors and return HTML where JSON or a real 404 should have appeared.

Forgetting to exclude asset-like paths is another common problem. A request for a missing JavaScript file should not silently become the SPA shell.

Putting index.html outside Spring's static-resource directories also breaks the forwarding setup.

Finally, if your API and SPA routes overlap in naming, no catch-all rule will stay clean for long. Separate namespaces make this pattern much safer.

Summary

• a Spring catch-all route is useful when Spring Boot serves an SPA and needs to forward client-side routes to index.html
• forward only non-API, non-static paths so real backend routes and assets keep working normally
• place index.html in Spring's static resource directory so forwarding can resolve it
• do not add a catch-all if Spring is only an API backend and the SPA is served elsewhere
• clear route namespaces such as /api make the whole pattern safer and easier to maintain