Chapter 29: Route Masking

Core Idea

Route masking displays a different URL in the browser's address bar than the route actually being navigated to internally, by storing the real location under a __tempLocation key in browser history.state, useful for things like showing a clean URL while internally rendering a modal/detail route.

Key Concepts

• Masking Mechanism: The actual runtime location is stored in location.state.__tempLocation; when present, the router uses that stored location instead of the one parsed from the visible URL.
• Imperative Masking: Pass a mask option to <Link> or navigate(), alongside the normal to/params/search, fully type-checked.
• Declarative Masking: Configure routeMasks on the router using createRouteMask(), centralizing mask rules rather than specifying them at each call site.
• URL Sharing Behavior: Since mask data lives only in local browser history state, a shared/copied URL automatically reveals the real (unmasked) route to anyone else who opens it.
• Reload Behavior: By default, URLs are NOT unmasked on page reload (the state persists in the history stack); set unmaskOnReload: true at the router level, on a specific route mask, or on an individual navigation call to force unmasking after reload.

Key Takeaways

1. Route masking is a client-side-only presentation layer, the real route is always what the server/router actually resolves; shared/copied links and (by default) reloaded pages reveal or retain the real vs. masked state predictably.
2. Use declarative routeMasks + createRouteMask() when a masking rule should apply consistently across the app; use the per-Link/navigate mask option for one-off cases.
3. Set unmaskOnReload: true explicitly if you want a masked URL to revert to the real route path after a hard refresh, this is opt-in, not the default.

Connects To

• Ch 23: Navigation, the mask field lives inside ToOptions, used by Link/navigate.
• Ch 22: URL Rewrites, another mechanism for showing a different URL than the internal one, but rewrite-based rather than history-state-based and not tied to a specific navigation.