History Session Manager

Common errors

• TypeError: (0 , history__WEBPACK_IMPORTED_MODULE_0__.createBrowserHistory) is not a function

  cause 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'?

  cause 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.

  cause 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`.

Warnings

• breaking Version 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.
• breaking Type 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>`.
• breaking The `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.
• gotcha Since 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.

Install

• npm install history npm
• yarn add history yarn
• pnpm add history pnpm

Imports

• createBrowserHistory
  wrong:

  const createBrowserHistory = require('history').createBrowserHistory;

  correct:

  import { createBrowserHistory } from 'history';

  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
  wrong:

  import createPath from 'history/createPath';

  correct:

  import { createPath } from 'history';

  All core utilities like `createPath`, `parsePath`, `createLocation`, `createMemoryHistory`, `createHashHistory`, etc., are available as named exports directly from the main 'history' package entry point.

Quickstart

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);