Route Guards and the Emerging Navigation API for SPA Routing

Route Guards

Route guards are mechanisms that execute custom logic at various stages of a navigation change, allowing developers to react before, during, or after a page transition.

SPA & History API

In single‑page applications (SPA), route guards are crucial. The typical implementation relies on the History API, using window.history.pushState and window.history.replaceState to modify the URL and listening to window.onpopstate or window.onhashchange to detect navigation.

Undetectable pushState & replaceState

The History API cannot directly detect calls to pushState or replaceState , which many UI interactions depend on to update the view.

Two common solutions exist:

Solution One

Register custom listeners and wrap pushState and replaceState with new functions that invoke the original methods and then notify the listeners. React‑Router follows this pattern.

However, this approach requires every module to use the wrapped methods, limiting its universality.

Solution Two

Overwrite the global window.history.pushState and window.history.replaceState methods to provide a centralized solution. Example implementation:

const rewrite = function(type) {
  const hapi = history[type];
  return function() {
    // custom logic can be added here
    const res = hapi.apply(this, arguments);
    // dispatch a synthetic popstate event so other listeners can react
    const eventArguments = createPopStateEvent(window.history.state, type);
    window.dispatchEvent(eventArguments);
    return res;
  };
};

history.pushState = rewrite("pushState");
history.replaceState = rewrite("replaceState");

Garfish adopts this technique, but overwriting global methods can cause side effects, such as duplicate listener executions when other modules also trigger navigation.

Navigation API Emerges

Chrome’s Navigation API offers a native, centralized way to handle navigation. It introduces a navigate event that fires for most address changes, including those triggered by pushState and replaceState .

NavigateEvent

Developers can listen to navigate and use transitionWhile() to supply a Promise representing the loading of the new view. The API also provides navigatesuccess and navigateerror events for resolved or rejected transitions.

navigation.addEventListener('navigate', navigateEvent => {
  if (isCatsUrl(navigateEvent.destination.url)) {
    const processNavigation = async () => {
      const request = await fetch('/cat-memes.json');
      const json = await request.json();
      // TODO: handle cat memes json
    };
    navigateEvent.transitionWhile(processNavigation());
  } else {
    // load other page
  }
});

Abort Signals for Navigation Cancellation

If a navigation is interrupted (e.g., the user clicks another link), the signal property provides an AbortSignal that can be passed to fetch to abort the request, preventing unnecessary work.

navigation.addEventListener('navigate', navigateEvent => {
  if (isCatsUrl(navigateEvent.destination.url)) {
    const processNavigation = async () => {
      const request = await fetch('/cat-memes.json', { signal: navigateEvent.signal });
      const json = await request.json();
      // TODO: handle json
    };
    navigateEvent.transitionWhile(processNavigation());
  } else {
    // load other page
  }
});

Entries

The API defines NavigationHistoryEntry objects representing each navigation session, exposing properties such as url , key , id , index , and sameDocument , as well as methods like getState() and an ondispose handler.

Navigation Operations

navigation.navigate(url, { state, history }) – similar to pushState / replaceState but supports cross‑origin URLs.

navigation.reload({ state }) – reloads the current page.

navigation.back() and navigation.forward() – move through the history stack.

navigation.traverseTo(key) – jump to a specific entry by its unique key.

Limitations

The Navigation API is new and currently only supported in recent Chrome versions (starting from Chrome 102), limiting its immediate adoption.

Outlook

While the article does not aim to be an exhaustive tutorial, it highlights the challenges of using the History API for SPA routing and presents the Navigation API as a promising, more native alternative that may become the primary solution in the near future.

References

https://developer.chrome.com/docs/web-platform/navigation-api

https://wicg.github.io/navigation-api/

❤️ Thank You for Your Support

Hope this share helps you. Please like, share, and follow the ELab team for more high‑quality articles.