vhistory

1.0.1 verified Fri May 01 auth: no javascript

A JavaScript library for managing browser session history anywhere JavaScript runs. vhistory 1.0.1 is a repackaged version of the popular `history` library by ReactTraining, abstracting environment differences and providing a minimal API to manage the history stack, navigate, confirm navigation, and persist state between sessions. It supports ES6 import and CommonJS require, with a UMD build available on unpkg. Key differentiators: simple API with `createHistory`, `push`, `replace`, `listen`, `goBack`, and `goForward` methods; compatible with browser and server-side environments.

Common errors

error TypeError: (0 , _vhistory.createHistory) is not a function ↓

cause Using a default import instead of named import.

fix

Change import createHistory from 'vhistory' to import { createHistory } from 'vhistory'.

error Cannot read property 'listen' of undefined ↓

cause Calling `history.listen` before `createHistory()` returns a valid object, or using `window.history` instead of `window.History`.

fix

Ensure const history = createHistory(); returns an object, and if using UMD, use window.History.createHistory().

error Module not found: Can't resolve 'vhistory' ↓

cause The package is not installed or the import path is incorrect.

fix

Run npm install --save vhistory and ensure import path is 'vhistory' (not 'history').

Warnings

gotcha The package is named `vhistory` on npm but the GitHub repository and documentation refer to `history`. Ensure you install `vhistory`, not `history`, as `history` is a different package. ↓

fix Install using `npm install --save vhistory` and import from `'vhistory'`.

gotcha The UMD bundle expects `window.History` (capital H) as the global variable. Using `window.history` will refer to the native browser History API, not the library. ↓

fix Access via `window.History.createHistory()` or destructure: `const { createHistory } = window.History`.

gotcha The `history` package v1.x (and thus vhistory) is a legacy API. The newer v3/v4 versions of the original `history` package have a different API (e.g., `createBrowserHistory`). vhistory reflects the older API for compatibility. ↓

fix If upgrading to modern versions, use `history` package v4+ and methods like `createBrowserHistory`.

Install

npm install vhistory

yarn add vhistory

pnpm add vhistory

Imports

createHistory

wrong

import createHistory from 'vhistory'

correct

import { createHistory } from 'vhistory'

Default import is not available; must use named import.

createHistory (CommonJS)
wrong
```
const createHistory = require('vhistory')
```
correct
```
const { createHistory } = require('vhistory')
```
CommonJS require returns an object; destructure to get createHistory.

UMD global

wrong

const history = window.history.createHistory()

correct

const history = window.History.createHistory()

UMD build exposes `window.History` (capital H), not `window.history`.

Quickstart

Demonstrates basic usage: create a history object, listen for location changes, push a new entry, and stop listening.

import { createHistory } from 'vhistory';

const history = createHistory();

const unlisten = history.listen(location => {
  console.log('Current location:', location.pathname);
});

history.push({
  pathname: '/about',
  search: '?from=home',
  state: { detail: 'example' }
});

// Later, stop listening
unlisten();