navigation-ponyfill

navigation-ponyfill is a polyfill for the browser Navigation API, designed to facilitate tracking of browser history navigation within single-page applications (SPAs). This ponyfill provides reasonably reliable detection of the user's ability to navigate backward, enhancing the user experience by aligning it with native browser behaviors.

Overview

Unlike traditional polyfills that modify the global environment, a ponyfill exports functionality as a module. navigation-ponyfill boasts zero runtime dependencies and intelligently defers to the native Navigation object on window.navigation when available, ensuring compatibility and minimal overhead.

Use Cases

The primary motivation for developing this ponyfill is to improve the operation of back buttons in SPAs. In scenarios where history.back() is utilized, it ensures that users remain within the application rather than being bounced off to external sites. This functionality is essential for creating a seamless navigation experience across various applications, including popular platforms like Instagram, Twitter, and Bluesky.

Implementing navigation correctly can be complex, especially when dealing with the History API. navigation-ponyfill simplifies this by enabling developers to easily manage previous URLs through history.pushState({ previousUrl }, '', newUrl), which is often challenging to implement consistently across different frameworks, including Next.js.

Quick Start

To quickly use navigation-ponyfill in a TypeScript project, follow this code snippet:

import { navigation } from 'navigation-ponyfill'

// Check if back navigation is available
if (navigation.canGoBack) {
  history.back()
}

// Access the current entry and history entries
console.log('Current URL:', navigation.currentEntry?.url)
console.log('History length:', navigation.entries().length)

// Listen for navigation changes
navigation.addEventListener('currententrychange', (event) => {
  console.log('Navigated:', event.navigationType) // 'push' | 'replace' | 'traverse'
  console.log('From:', event.from.url)
  console.log('To:', navigation.currentEntry?.url)
})

Entry Points

The package offers two main entry points:

1. Default (with side effects):

   import { navigation } from 'navigation-ponyfill'
   

   This entry point returns the native window.navigation, or alternatively, it modifies history.pushState and history.replaceState to provide the ponyfill functionality. This approach is recommended for most applications.

2. Core (side-effect-free):

   import { createNavigation, Navigation } from 'navigation-ponyfill/core'
   

   This method allows developers to control the initialization of the Navigation instance and is useful for testing or advanced use cases.

Supported APIs

navigation-ponyfill implements a significant subset of the Navigation API specification, supporting core functionalities including:

• currentEntry
• canGoBack
• canGoForward
• entries()

Caveats

While navigation-ponyfill increases compatibility for multi-page applications (MPAs), it should be loaded on every page to prevent state corruption. It also imposes certain constraints on the use of the History API, particularly that state objects must be either objects or nullish values.

This ponyfill is a valuable tool for developers looking to enhance their application's navigation capabilities with minimal hassle while preserving a focus on user experience.