history-server

1.3.1 verified Sat Apr 25 auth: no javascript maintenance

An HTTP server for single-page apps that use the HTML5 history API. Version 1.3.1 is the latest stable release, with no recent updates since 2017. It serves multiple single-page apps from various directories or different hosts on the same domain, supporting both static file serving and proxying. Unlike other SPA servers (e.g., serve, http-server), history-server is designed specifically for apps using pushState, with built-in support for multiple app configurations via config file or directory layout. It is a lightweight CLI tool but can also be used programmatically in Node.js.

Common errors

error TypeError: createServer is not a function ↓

cause Importing default export instead of named export.

fix

Use const { createServer } = require('history-server');

error 404 page not found for /some/path ↓

cause The app's index.html not found at the root of the configured path.

fix

Ensure index.html exists in the root directory of the app and the path mapping is correct.

error EADDRINUSE: port already in use :::80 ↓

cause Another process already listening on the same port.

fix

Change port via -p flag or server.listen(port) to a different port.

Warnings

breaking createServer no longer accepts a single app object; must pass an array since v1.0.0. ↓

fix Wrap a single app in an array: createServer([app]).

deprecated Server options (e.g., port) passed via second argument to createServer deprecated; use returned server methods. ↓

fix Call server.listen(port) instead of passing options.

gotcha Relative paths in proxy configuration resolve from process.cwd(), not the config file location. ↓

fix Always use absolute paths or resolve relative to __dirname.

Install

npm install history-server

yarn add history-server

pnpm add history-server

Imports

createServer

wrong

const { createServer } = require('history-server')

correct

import { createServer } from 'history-server'

CJS require works as well but ESM import is preferred when using ES modules.

default
wrong
```
const historyServer = require('history-server').default
```
correct
```
import historyServer from 'history-server'
```
Package has no default export; importing default gives undefined. Use named import createServer.
createServer
wrong
```
const createServer = require('history-server')
```
correct
```
const { createServer } = require('history-server')
```
Direct require returns an object with createServer property, not the function itself.

Quickstart

Shows how to use history-server both via CLI and programmatically to serve a single SPA from a directory.

// CLI usage:
// $ npx history-server app
// Or programmatically:
const path = require('path');
const { createServer } = require('history-server');

const server = createServer([
  {
    path: '/',
    root: path.join(__dirname, 'public')
  }
]);

server.listen(3000, () => {
  console.log('Listening on port 3000');
});