baseline
manual

Routing ​

Express Routing Order ​

Express processes requests based on the order in which handlers are defined. The stack follows this sequence (first matching wins):

  1. API routes under /api
  2. Static file serving under /files
  3. User-defined routes (configured via options.init)
  4. Frontend assets (served by Vite in development or express.static in production)

Routing Precedence

If no routes match the sequence above, a final handler returns a plain 404 response without content. You must define your custom logic within the options.init function to ensure it is evaluated before this fallback handler; otherwise, any routes defined after the 404 handler will be ignored.

Frontend Routing Modes ​

See Configuration

api Mode (Default) ​

API mode is the default routing configuration for baseline. In this mode, index.html is only served under the root (/) route. Any undefined path returns an HTTP 404 error. This mode is designed for using Vue Router in Hash Mode.

Using Hash Mode ensures that navigation remains client-side, meaning real HTTP requests are only made when interacting with actual backend endpoints or static files.

html5 Mode ​

The default behavior of vite-express is to resolve the current request path to the nearest .html file. In a standard baseline SPA, this always resolves to index.html, regardless of the URL path. This enables compatibility with Vue Router's HTML5 Mode.

Use with caution

While HTML5 mode provides "clean" URLs (e.g., /dashboard instead of /#/dashboard), it introduces several technical trade-offs:

  • Fake Visits: Navigation within the application triggers internal browser history changes rather than actual HTTP requests to the backend.
  • Path Collisions: Client-side routes can conflict with backend endpoints. For example, if you define /files as a frontend route, it will function during SPA navigation; however, refreshing the page makes it a real HTTP request, causing the backend's /files handler to take precedence.
  • Fallback Complexity: The backend must serve SPA assets for all paths to ensure that direct URL entry works. This prevents the server from returning accurate 404 errors for invalid requests because index.html is always served, shifting all error handling responsibilities to the frontend.
  • Resolution Overhead: The template resolution logic in vite-express iterates through filesystem paths to locate an index.html file, which adds slight overhead to each request.