Principle:OpenHands OpenHands Frontend Serving
| Knowledge Sources | |
|---|---|
| Domains | Server_Architecture, SaaS_Infrastructure |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Serving a single-page application with HTML5 history mode fallback from a static directory enables the backend server to host the frontend without requiring a separate web server or CDN for client-side routing.
Description
The Frontend Serving principle addresses how a SaaS server delivers its web-based user interface to browsers. Single-page applications (SPAs) use client-side routing where the browser URL changes without triggering a full page reload. This creates a challenge for the server: when a user navigates directly to a deep URL (such as /workspace/project-123), the server must return the SPA's index.html rather than a 404 error, because the route exists only in the client-side router. The SPA serving pattern solves this by mounting a static file directory that serves built frontend assets (JavaScript bundles, CSS, images) for known file paths and falls back to index.html for all other paths. This fallback behavior is commonly called HTML5 history mode support.
Usage
Apply this principle when the backend server is responsible for serving the frontend SPA in addition to the API. This is common in self-contained deployments where running a separate web server (such as Nginx) for static files is undesirable. The SPA mount should be registered last in the router chain, after all API routes, so that API endpoints take precedence over the catch-all fallback behavior.
Theoretical Basis
The SPA serving pattern combines two concepts: static file serving and fallback routing. Static file serving maps URL paths directly to filesystem paths within a designated directory, returning files with appropriate MIME types and caching headers. Fallback routing extends this by defining a default response for any path that does not match an existing file: instead of returning a 404, the server returns the index.html entry point, allowing the client-side JavaScript router to interpret the URL and render the appropriate view. This pattern must be mounted at the lowest priority (typically the root path /) to ensure it does not intercept API routes or other server-handled paths. The ordering guarantee is critical: FastAPI processes routes in registration order, so mounting the SPA catch-all last ensures that all explicit API routes are matched first.