Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Introduction

Single-page applications (SPAs) such as those built with React, Angular, or Vue often rely on client-side routing. When served from a Spring Boot backend, refreshing the page or accessing a wrong link sends a request for a non-existent server path. Spring Boot then returns a 404 error.

To make the SPA work correctly, we need to forward all unmatched requests to index.html with HTTP status 200. This lets the frontend router handle the path.

In this tutorial, we’ll learn how to configure Spring Boot so that all unknown routes are redirected to the SPA’s index.html.

2. Maven Dependency

Let’s start by importing the spring-boot-starter-web dependency to our pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.3.2</version>
</dependency>

3. Setting Up a Basic SPA with Spring Boot

Let’s consider an SPA deployed with Spring Boot, where the compiled frontend files are placed inside the resources directory:

src/main/resources/static

For example, a minimal index.html could look like:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Baeldung</title>
</head>
<body>
    <h1>Home Page</h1>
</body>
</html>

Next, we create a simple controller to forward the root path:

@Controller
public class HomeController {
    @RequestMapping("/")
    public String getHome(){
        return "forward:/index.html";
    }
}

When a user accesses the root path http://localhost:8080/, Spring Boot serves index.html correctly.

However, if the user refreshes a client-side route like http://localhost:8080/dashboard, Spring Boot tries to find a server mapping for /dashboard and returns 404 Not Found. Instead, we want Spring Boot to return index.html so the SPA router can handle the route.

4. Redirecting 404 Not Found Errors

In this section, we describe some solutions for redirecting unmatched requests to index.html.

4.1. Using a Controller to Forward Unknown Routes

Let’s create a controller that forwards all unmapped paths to index.html:

@Controller
public class SpaForwardController {
    @RequestMapping(value = "/{path:[^\\.]*}")
    public String redirect() {
        return "forward:/";
    }
}

The unmatched requests without a file extension are forwarded to “/”, which returns index.html.

If a specific mapping exists (for example, @GetMapping(“/dashboard”)), Spring selects it with higher precedence, and the catch-all pattern is ignored. For any other path without a matching handler (such as /settings), the request falls through to the catch-all mapping and gets forwarded to index.html.

Also, we need to support deeper routes like /dashboard/settings. To do this, we can expand the controller mapping:

@Controller
public class SpaForwardController {
    @RequestMapping(value = {
        "/{path:[^\\.]*}",
        "/{path:[^\\.]*}/**/{subpath:[^\\.]*}"
    })
    public String redirect() {
        return "forward:/";
    }
}

4.2. Using a Custom Error Controller

Another approach is to intercept 404 errors and redirect them to the SPA entry point:

@Controller
public class SpaErrorController implements ErrorController {
    @RequestMapping("/error")
    public String handleError() {
        return "forward:/index.html";
    }
}

This method ensures that any unknown route eventually loads the SPA.

However, this approach may also intercept real backend 404 errors, which may not always be desirable.

4.3. Using WebMvcConfigurer

Another approach is to centralize error handling and avoid the need to explicitly match route patterns.

We can achieve this by implementing the WebMvcConfigurer interface and registering a custom error page:

@Configuration
public class WebApplicationConfig implements WebMvcConfigurer {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/notFound")
          .setViewName("forward:/index.html");
    }

    @Bean
    public WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> containerCustomizer() {
        return container -> {
            container.addErrorPages(new ErrorPage(HttpStatus.NOT_FOUND, "/notFound"));
        };
    }
}

In this configuration, any request that results in a 404 Not Found error is redirected to /notFound. This endpoint then forwards the request to index.html.

However, it also means that all 404 errors—including those from backend APIs—are redirected to the SPA, which may not always be desirable.

5. Test

After starting the Spring Boot application, we can verify the configuration by accessing different URLs.

First, we request the root path:

$ curl -i http://localhost:8080/

The response returns 200 along with the contents of index.html:

HTTP/1.1 200

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Baeldung</title>
</head>
<body>
    <h1>Home Page</h1>
</body>
</html>

Next, we simulate accessing a client-side route:

$ curl -i http://localhost:8080/dashboard

Instead of returning a 404 Not Found, the application responds with 200 and serves index.html. This confirms that the request is forwarded and handled by the SPA router.

6. Conclusion

In this article, we explored how to forward unknown routes to index.html when serving a single-page application with Spring Boot. We examined multiple approaches, including using a custom controller, configuring WebMvcConfigurer, and handling errors via a custom error mapping.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.
Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

2 Comments
Oldest
Newest