liveBook · Manning

Rewrite rule

As explained in Vanilla Web

A rewrite rule is server configuration that maps an incoming request path to a different resource or response without changing the requested URL.

A client-side router cannot handle a direct request until the server has returned a page. For a shell-based single-page application, a rewrite rule serves the entry HTML document for an application route while leaving the requested URL in place. The router then reads that URL and renders the matching view. section 10.2

Keep the fallback narrow:

  • Serve real files normally, including static assets. Let API endpoints return API responses rather than HTML. section 10.2 section 15.10
  • Use the entry HTML fallback for application paths without a matching file; the deployment configurations restrict that fallback to paths without a file extension. section 15.10
  • Return a real 404 Not Found for routes that should not exist. Returning the shell with 200 OK for every unknown path creates soft 404s. section 10.2
  • When deploying under a prefix such as /dashboard/, configure that base path in both the server rewrite and client router. section 10.2

A fallback that hides a missing file

A development server serves existing files and falls back to /index.html for app routes such as /products and /cart. A blanket rewrite would also turn a request for a missing /src/app.js into an HTML response, producing a browser MIME type error instead of revealing the missing file. section 15.10

Figure 10.2 A link in a shell-based SPA starts on the server, the server delivers the shell (index html) and then the client router in JavaScript is responsible for rendering the view based on the URL.
ch10 F002 firtman

The request sequence shows why the server must deliver the shell before JavaScript can select a view from the URL. section 10.2

Table 15.2 Deployment configuration files included with the sample
Host File Goes at

Vercel

vercel.json

Repository root

Netlify

netlify.toml

Repository root

Netlify, Cloudflare Pages

_redirects, _headers

Published root

Apache

.htaccess

Published root

Nginx

nginx.conf

Merged into the site config

Caddy

Caddyfile

Repository root

Firebase Hosting

firebase.json

Repository root

Azure Static Web Apps

staticwebapp.config.json

App root

GitHub Pages

404.html

Published root

Host-specific configuration files belong in the locations listed; keeping them together in a project folder does not activate them. section 15.10

A shell fallback is an architectural choice, not a requirement for every friendly URL. Server-side rendering and static site generation can instead provide route-specific HTML, which is often a better fit for public content that needs to be discoverable. section 10.2

How Vanilla Web covers it

How deep it goes
Details file-first and extensionless fallbacks, API exclusions, subpath alignment, and real 404 responses; leaves host-specific syntax to deployment configurations.
Examples
Uses /products and /cart as app routes and a missing /src/app.js request to expose blanket-rewrite failures.
What it assumes
Assumes a shell-based SPA with a client-side router and distinguishes the server's response from subsequent JavaScript rendering.
What you can do after
Operate/configure it to serve SPA routes without rewriting real files or API requests, and preserve 404 responses for invalid routes.
How it connects
Connects client-side routing to static asset serving, API routes, HTTP status codes, server-side rendering, and static site generation.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Vanilla Web. The section links point to the parts of the book it draws on.