Pushstate Server

Common errors

• Error: Cannot find module 'pushstate-server'

  cause 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

  cause 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.

  cause 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.

Warnings

• gotcha The 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.
• gotcha As 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.
• gotcha When 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).

Install

• npm install pushstate-server npm
• yarn add pushstate-server yarn
• pnpm add pushstate-server pnpm

Imports

• server
  wrong:

  import server from 'pushstate-server';

  correct:

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

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

  import { start } from 'pushstate-server';

  correct:

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

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

Quickstart

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

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

// Start a server for a single directory
server.start({
  port: process.env.PORT ?? 3000,
  directory: './public'
});

console.log(`Server started on port ${process.env.PORT ?? 3000} serving './public'.`);
console.log('Access your single-page app at http://localhost:3000');
console.log('e.g., http://localhost:3000/some/pushstate/route will serve index.html');

// Or for multiple directories
// server.start({
//   port: process.env.ANOTHER_PORT ?? 4200,
//   directories: ['./dist', './node_modules']
// });