{"id":11038,"library":"history","title":"History Session Manager","description":"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.","status":"active","version":"5.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/remix-run/history","tags":["javascript","history","location","typescript"],"install":[{"cmd":"npm install history","lang":"bash","label":"npm"},{"cmd":"yarn add history","lang":"bash","label":"yarn"},{"cmd":"pnpm add history","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const createBrowserHistory = require('history').createBrowserHistory;","symbol":"createBrowserHistory","correct":"import { createBrowserHistory } from 'history';"},{"note":"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.","symbol":"History","correct":"import type { History } from 'history';"},{"note":"All core utilities like `createPath`, `parsePath`, `createLocation`, `createMemoryHistory`, `createHashHistory`, etc., are available as named exports directly from the main 'history' package entry point.","wrong":"import createPath from 'history/createPath';","symbol":"createPath","correct":"import { createPath } from 'history';"}],"quickstart":{"code":"import { createBrowserHistory, createHashHistory, createMemoryHistory } from 'history';\n\n// Create a browser history instance for web applications\nconst browserHistory = createBrowserHistory();\n\nconsole.log('Initial browser history location:', browserHistory.location.pathname);\n\n// Listen for changes in the history stack\nbrowserHistory.listen(({ location, action }) => {\n  console.log(`Browser history changed: ${action} to ${location.pathname}${location.search}${location.hash}`);\n});\n\n// Navigate to a new path with state\nbrowserHistory.push('/about', { from: 'home' });\n\n// Replace the current entry in the history stack\nbrowserHistory.replace('/contact');\n\n// Create a hash history instance (for environments where server-side routing is not possible)\nconst hashHistory = createHashHistory();\n\nconsole.log('Initial hash history location:', hashHistory.location.pathname);\n\nhashHistory.push('/#/settings');\n\n// Create a memory history instance (useful for testing or server-side rendering)\nconst memoryHistory = createMemoryHistory({ initialEntries: ['/', '/dashboard'] });\nmemoryHistory.go(-1);\nconsole.log('Memory history location:', memoryHistory.location.pathname);\n\n// Example of blocking navigation using `history.block`\nconst unblock = browserHistory.block((tx) => {\n  console.warn(`Blocking navigation attempt to ${tx.location.pathname}.`);\n  // To proceed with the navigation, uncomment tx.retry();\n  // tx.retry();\n  // Returning false or nothing cancels the navigation.\n  return false; \n});\n\n// Attempt to navigate, which will be blocked by the above listener\nbrowserHistory.push('/secret-page');\n\n// Clean up the blocker after a timeout for demonstration\nsetTimeout(() => {\n  unblock(); // Remove the navigation blocker\n  console.log('Navigation blocker removed. Subsequent navigations will proceed.');\n  browserHistory.push('/allowed-page'); // This navigation will now succeed\n}, 2000);\n","lang":"typescript","description":"Demonstrates creating browser, hash, and memory history instances, listening for location changes, programmatic navigation (push/replace), and using the navigation blocking API with cleanup."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=5.3.0"},{"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>`.","message":"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>`.","severity":"breaking","affected_versions":">=5.2.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.2 <5.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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'`.","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).","error":"TypeError: (0 , history__WEBPACK_IMPORTED_MODULE_0__.createBrowserHistory) is not a function"},{"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 */ }`.","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.","error":"Property 'state' does not exist on type 'Location'. Did you mean 'State'?"},{"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`.","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.","error":"TS2307: Cannot find module 'history' or its corresponding type declarations."}],"ecosystem":"npm"}