history

2.1.1 verified Fri May 01 auth: no javascript maintenance

A JavaScript library for managing session history in any JavaScript environment. Version 2.1.1 (stable) provides a minimal API to manage the history stack, navigate, confirm navigation, and persist state. It abstracts away differences between browser, Node, and other environments. Key differentiator: it is the core dependency behind React Router v4, offering createHistory, createHashHistory, and createMemoryHistory. Release cadence is infrequent; v2 is stable but superseded by v4 (ESM) and v5 (React Router). Note: This version uses CommonJS; ESM was introduced in later versions.

Common errors

error Attempted import error: 'createHistory' is not exported from 'history'. ↓

cause Trying to import named export from default CommonJS module without proper ESM interop in bundler.

fix

Use require('history').createHistory or configure bundler (e.g., webpack) to handle CommonJS named exports.

error history is not defined ↓

cause Using createHistory() in Node.js environment without browser history API.

fix

Use createMemoryHistory() instead of createHistory() in Node.js.

error TypeError: history.listen is not a function ↓

cause Calling listen on a history object that was not created by createHistory (e.g., using default import).

fix

Ensure you use createHistory (or createMemoryHistory) to create the history object.

error Cannot read property 'pathname' of undefined ↓

cause Trying to access location.pathname before location is defined or inside uninitialized listener.

fix

Check that location is defined: const location = history.getCurrentLocation(); or wait for listener to fire.

Warnings

breaking v2 does not support ESM imports directly; use require or a bundler that handles CommonJS. ↓

fix Use require() or configure bundler for CommonJS. For ESM, upgrade to v4+.

deprecated useQueries and useBasename are deprecated in v2; they were removed in later versions. ↓

fix Avoid using them; they are not present in v2.1.1 final? Actually they were removed earlier. Check docs.

gotcha Default export from 'history' is the module object, not createHistory. Named exports only. ↓

fix Use named import: import { createHistory } from 'history'.

gotcha createHistory() uses window.history; fails in Node.js without polyfill. Use createMemoryHistory instead. ↓

fix For server-side rendering, use createMemoryHistory or check if window exists.

breaking v2 listener signature: (location) => void. In v3+, includes action and other params. ↓

fix Update listeners when upgrading to v3: (location, action) => void.

Install

npm install create-history

yarn add create-history

pnpm add create-history

Imports

createHistory

wrong

import createHistory from 'history' // default export is not createHistory

correct

import { createHistory } from 'history'

v2 only has named exports. Default export is the module object.

createHashHistory

wrong

var createHashHistory = require('history').createHashHistory // correct but not wrong

correct

import { createHashHistory } from 'history'

Uses browser hash-based routing.

createMemoryHistory

wrong

import createMemoryHistory from 'history' // wrong: no default export

correct

import { createMemoryHistory } from 'history'

For non-browser environments like React Native or testing.

useQueries

wrong

const useQueries = require('history/useQueries') // wrong: path does not exist

correct

import { useQueries } from 'history'

Deprecated in v2? Not available in v2.1.1 — no such export. Check documentation.

Quickstart

Shows how to create a browser history, listen for location changes, push a new entry, and use memory history in non-browser environments.

const { createHistory, createMemoryHistory } = require('history');
// or use import { createHistory } from 'history' with ESM bundler

const history = createHistory(); // browser history

// Get the current location
const location = history.getCurrentLocation();
console.log(location.pathname);

// Listen for changes
const unlisten = history.listen((location) => {
  console.log('New location:', location.pathname);
});

// Push a new entry
history.push({
  pathname: '/new-path',
  search: '?query=example',
  state: { user: 'jane' }
});

// Stop listening
unlisten();

// In Node.js, use memory history:
const memoryHistory = createMemoryHistory();
memoryHistory.push('/home');