Registry / web-framework / pushstate-server

pushstate-server

library3.1.0jsnpmunverified

Pushstate Server is a minimalistic static file server designed to work seamlessly with HTML5 Pushstate, a browser API for manipulating browser history. It addresses the common single-page application (SPA) routing problem where direct access to a deep link (e.g., `/users/123`) would result in a 404 error because no physical file exists at that path on the server. Instead, this server is configured to return the `index.html` file for any route that does not directly map to a static asset. Conversely, requests for actual static files (e.g., `/assets/logo.png`) are served directly. The package is currently at version 3.1.0. Its release cadence appears to be very slow or effectively ceased, with the last publish on npm dating back over seven years to February 12, 2019. Key differentiators include its simple configuration for HTML5 Pushstate routing, supporting multiple directories for serving static assets, and binding to specific hosts or ports. It remains a lightweight solution for basic SPA hosting needs, though its lack of recent updates may pose compatibility or security considerations for modern development workflows.

web-framework

npm install pushstate-server

github ↗package ↗

INSTALL

IMPORT

SIG · PUSHSTATE-SERVER

pushstate-server

web-frameworkjavascriptv3.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

server

✓ const server = require('pushstate-server');

✗ import server from 'pushstate-server';

This package is a CommonJS module. Direct ESM imports are not supported without a transpilation step or dynamic import.

start

✓ const server = require('pushstate-server'); server.start({ port: 3000, directory: './public' });

✗ import { start } from 'pushstate-server';

The `start` function is a method of the exported `server` object, not a named export itself.

Demonstrates how to initialize and start the pushstate-server for serving static files from a single directory.

pushstate-server --version

Debug

Known issues

gotchaThe package has not been updated in over seven years (last published Feb 12, 2019). It is a CommonJS module and does not natively support ES Modules (ESM) syntax, which is the standard for modern JavaScript development. Projects using ESM will need to use `require()` or a transpilation layer.

fix

For ESM projects, use `require()` for this package or consider alternative static servers with active maintenance and ESM support. Ensure your build pipeline correctly handles CJS dependencies.

affects: >=3.1.0

gotchaAs a static file server, `pushstate-server` relies on proper configuration to prevent security vulnerabilities. Serving sensitive files or directories that contain user-uploaded content without proper validation could lead to exposure or path traversal attacks.

fix

Always ensure the `directory` or `directories` option points only to trusted static asset folders. Avoid serving root directories or user-generated content directly without additional security layers. Regularly review your server's exposed paths.

affects: >=3.0.0

gotchaWhen using the `file` option to specify a custom entry point (e.g., `app.html` instead of `index.html`), ensure that the client-side routing logic correctly references this file for non-static routes. Misconfiguration can lead to blank pages or incorrect content being served.

fix

Verify that your client-side routing framework (e.g., React Router, Vue Router) is configured to expect the custom entry file. Test all routes, including direct URL access and browser history navigation (back/forward buttons).

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'pushstate-server'

The 'pushstate-server' package has not been installed or is not accessible in the current project environment.

fix

Run `npm install pushstate-server` or `npm install -g pushstate-server` if using the global CLI. Ensure the package is listed in `package.json` dependencies if it's a project-specific dependency.

EADDRINUSE: address already in use :::3000

The specified port (e.g., 3000) is already being used by another process on your system.

fix

Change the `port` option in your server configuration to an available port, or terminate the process currently using the desired port. You can often use `process.env.PORT` to allow dynamic port assignment.

Client-side `history.pushState()` or `history.replaceState()` does not correctly load content after browser refresh.

While `pushstate-server` ensures non-static routes return `index.html`, the client-side JavaScript might not correctly re-initialize the application state or render the appropriate view when the browser performs a full refresh on a deep link. This is a common issue with HTML5 Pushstate SPAs if the client-side rendering logic isn't robust enough to handle initial load on arbitrary URLs.

fix

Ensure your single-page application's client-side router is configured to read the current URL path on initial load and render the corresponding component. The `pushstate-server` provides the necessary `index.html`, but the SPA framework must take over routing from there.

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/scottcorgan/pushstate-server ↗

packagehttps://www.npmjs.com/package/pushstate-server ↗