Registry / web-framework / history

history

JSON →
library5.3.0jsnpmunverified

The `history` library provides a robust and environment-agnostic API for managing session history in JavaScript applications, abstracting away the complexities of different platforms (browser, hash, memory). It allows developers to manage the history stack, navigate programmatically, and persist state across sessions. The current stable version is 5.3.0. Releases are generally aligned with React Router versions, as it's a core dependency for React Router v6. Key differentiators include its pluggable architecture for different history implementations (browser, hash, memory) and its strong TypeScript support, making it suitable for both web applications and server-side rendering or testing environments. It offers a consistent API regardless of the underlying history mechanism, simplifying routing logic in SPAs.

npm install history
INSTALL
IMPORT
SIG · HISTORY
H
history
web-frameworkjavascriptv5.3.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createBrowserHistory
import { createBrowserHistory } from 'history';
const createBrowserHistory = require('history').createBrowserHistory;
For modern applications, use ESM named imports. While CommonJS `require` still functions, it is generally discouraged for new development or within native ESM contexts as of v5.3.0.
History
import type { History } from 'history';
Since v5.0.0-beta.5, TypeScript types are built directly into the package. Use `import type` for type-only imports to avoid bundling issues.
createPath
import { createPath } from 'history';
import createPath from 'history/createPath';
All core utilities like `createPath`, `parsePath`, `createLocation`, `createMemoryHistory`, `createHashHistory`, etc., are available as named exports directly from the main 'history' package entry point.

Demonstrates creating browser, hash, and memory history instances, listening for location changes, programmatic navigation (push/replace), and using the navigation blocking API with cleanup.

import { createBrowserHistory, createHashHistory, createMemoryHistory } from 'history'; // Create a browser history instance for web applications const browserHistory = createBrowserHistory(); console.log('Initial browser history location:', browserHistory.location.pathname); // Listen for changes in the history stack browserHistory.listen(({ location, action }) => { console.log(`Browser history changed: ${action} to ${location.pathname}${location.search}${location.hash}`); }); // Navigate to a new path with state browserHistory.push('/about', { from: 'home' }); // Replace the current entry in the history stack browserHistory.replace('/contact'); // Create a hash history instance (for environments where server-side routing is not possible) const hashHistory = createHashHistory(); console.log('Initial hash history location:', hashHistory.location.pathname); hashHistory.push('/#/settings'); // Create a memory history instance (useful for testing or server-side rendering) const memoryHistory = createMemoryHistory({ initialEntries: ['/', '/dashboard'] }); memoryHistory.go(-1); console.log('Memory history location:', memoryHistory.location.pathname); // Example of blocking navigation using `history.block` const unblock = browserHistory.block((tx) => { console.warn(`Blocking navigation attempt to ${tx.location.pathname}.`); // To proceed with the navigation, uncomment tx.retry(); // tx.retry(); // Returning false or nothing cancels the navigation. return false; }); // Attempt to navigate, which will be blocked by the above listener browserHistory.push('/secret-page'); // Clean up the blocker after a timeout for demonstration setTimeout(() => { unblock(); // Remove the navigation blocker console.log('Navigation blocker removed. Subsequent navigations will proceed.'); browserHistory.push('/allowed-page'); // This navigation will now succeed }, 2000);
Debug
Known issues
breakingVersion 5.3.0 introduced native ESM consumption for all exports. While this aligns with modern JavaScript module standards, it might require adjustments for older build tools, Node.js versions, or environments that previously relied on specific CommonJS export behaviors or non-standard ESM patterns. Ensure your tooling is configured for native ESM.
fix
Update your bundler configuration (e.g., Webpack, Rollup, Vite) to correctly handle native ESM modules. For Node.js, ensure you are using a version that supports `type: 'module'` in `package.json` or `.mjs` extensions, and prefer ESM `import` statements.
affects: >=5.3.0
breakingType declarations for `State`, `PartialPath`, and `PartialLocation` were deprecated in v5.2.0. The `State` type is now `unknown`, requiring explicit consumer type narrowing at runtime. `PartialPath` should be replaced with `Partial<Path>`, and `PartialLocation` with `Partial<Location>`.
fix
Review your TypeScript codebase for usages of `State`, `PartialPath`, and `PartialLocation`. Update `State` handling to incorporate type guards or assertions to narrow the `unknown` type. Replace `PartialPath` with `Partial<Path>` and `PartialLocation` with `Partial<Location>`.
affects: >=5.2.0
breakingThe `Location` type generic for state was removed in v5.0.2, causing potential type conflicts. Although `location.state` was subsequently typed as `any` and the `State` type export restored in v5.1.0 for compatibility, direct usage of `Location<T>` for strongly typing `state` is no longer supported as it was in v4.
fix
If you relied on `Location<T>` for strong type-checking of `location.state`, you will need to adapt. For versions 5.1.0 and later, `location.state` will typically be `any` or `unknown`, requiring runtime type checks, explicit casting, or use of the exported `State` type with manual narrowing.
affects: >=5.0.2 <5.2.0
gotchaSince v5.0.0-beta.5 (and stable v5.0.0), the `history` library includes its own TypeScript type definitions. Installing `@types/history` alongside `history@5` will lead to duplicate type declarations and compilation errors.
fix
If you are using `history` v5 or newer, uninstall `@types/history` from your project: `npm uninstall @types/history` or `yarn remove @types/history`. Ensure your `tsconfig.json` is correctly configured to pick up the built-in types.
affects: >=5.0.0
Errors
Common errors & fixes
TypeError: (0 , history__WEBPACK_IMPORTED_MODULE_0__.createBrowserHistory) is not a function
This error typically occurs when a CommonJS module attempts to consume `history` as an ESM-only default export, or when there's a mismatch in how named exports are handled in a mixed CJS/ESM environment (e.g., Webpack's interpretation).
fix
Ensure your project is configured for native ESM if you're using `import` statements. If using `require()`, adapt to `const { createBrowserHistory } = require('history');` for named exports, or configure your bundler to handle ESM interop correctly, especially in Node.js environments with `type: 'module'`.
Property 'state' does not exist on type 'Location'. Did you mean 'State'?
This TypeScript error indicates an attempt to access `location.state` when the `Location` type no longer includes a strongly typed `state` property, specifically after the changes in v5.0.2 and v5.1.0.
fix
For `history` v5, `location.state` is typed as `any` or `unknown`. Access `location.state` directly, and apply runtime type narrowing or explicit type assertions if you expect a specific type, e.g., `const myState = history.location.state as { from: string };` or `if (typeof history.location.state === 'object' && history.location.state !== null) { /* safe access */ }`.
TS2307: Cannot find module 'history' or its corresponding type declarations.
TypeScript cannot locate the type definitions for the `history` package. This can happen if the package is not installed, if `@types/history` is missing (for `history` v4), or if `@types/history` is conflicting with `history` v5's built-in types.
fix
For `history` v5 and newer, types are bundled. Ensure `history` is correctly installed via `npm install history`. If on `history` v4, install `@types/history` (`npm install --save-dev @types/history`). If on `history` v5 and still seeing this, ensure you have removed `@types/history`.
Upgrade
Version history
5.3.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
6
Resources