history

history is a small, dependency-light JavaScript library that abstracts the differences between browser navigation environments behind a single, consistent API. It provides three interchangeable history implementations — browser history (backed by the HTML5 History API), hash history (for servers you don’t control), and memory history (for tests and React Native) — so the same push/replace/go/listen calls work identically regardless of where the app runs.

Most developers encounter history indirectly: it is the navigation engine underneath React Router, handling the actual pushState/replaceState/popstate plumbing so routing libraries can focus on matching and rendering. It exposes typed Location, Action, and Update primitives plus createPath/parsePath helpers for working with URL segments directly.

What You Get

• createBrowserHistory for standard HTML5 pushState/replaceState-based routing in web browsers
• createHashHistory for storing location in the URL fragment when the server can’t be configured for client-side routing
• createMemoryHistory for stateful non-browser environments such as tests and React Native, with a readable stack index
• A shared History interface (action, location, push, replace, go, back, forward, listen, block, createHref) so app code is portable across environments
• createPath and parsePath utilities for converting between string URLs and {pathname, search, hash} objects
• Navigation blocking via history.block() to prompt users before leaving a page with unsaved changes

Common Use Cases

• Powering client-side routing under React Router or a custom router that needs a normalized navigation API
• Building a single-page app that must support both standard browser URLs and hash-based routing for static hosting
• Driving navigation in React Native or other non-DOM environments via createMemoryHistory
• Implementing ‘unsaved changes’ confirmation prompts before allowing navigation away from a form
• Writing router or navigation-aware component tests against a controllable in-memory history stack

Under The Hood

Architecture — index.ts implements three factory functions (createBrowserHistory, createHashHistory, createMemoryHistory) that share one internal pattern: each closure maintains a mutable action/location pair, an event bus (createEvents) for listeners and blockers, and helpers (getIndexAndLocation, getNextLocation, applyTx) that keep the tracked state in sync with the underlying source of truth. Browser and hash histories wrap the native window.history object (pushState/replaceState and the popstate/hashchange events); memory history instead keeps an in-memory array of Location entries with an index pointer. All three satisfy the same History interface, which is what lets React Router and other consumers swap environments without changing call sites.

Tech Stack — Written entirely in TypeScript and compiled with Rollup (rollup-plugin-typescript2) into CJS, ESM, and UMD bundles; Babel with babel-plugin-dev-expression strips dev-only warning code from production builds. The package has zero runtime dependencies besides @babel/runtime helpers, and the repo is an npm workspace with a single publishable package (packages/history). Tests run through Karma + Mocha across real browsers via BrowserStack, plus a Node-based runner for memory history.

Code Quality — The tests directory contains dedicated suites for browser, hash, and memory histories, along with shared TestSequences fixtures that are run against all three implementations to guarantee consistent behavior. Every exported type and function carries JSDoc comments linking back to the docs site, and a small warning() helper surfaces dev-time console warnings (e.g. for relative pathnames or navigation to unrecognized locations) instead of failing silently. Strict TypeScript typing is used throughout with no any leakage in the public surface.

API Design — A single History interface (action, location, push, replace, go, back, forward, listen, block, createHref) is shared across all three environments, so there is exactly one API to learn regardless of target platform. The surface area is intentionally small — a handful of factory functions plus createPath/parsePath — and is backed by a docs/ directory covering getting-started, installation, navigation, and blocking-transitions guides in addition to inline JSDoc, giving new users a fast path to productivity even though the project itself has been in maintenance mode since 2022.