{"id":11602,"library":"pushstate-server","title":"Pushstate Server","description":"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.","status":"maintenance","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/scottcorgan/pushstate-server","tags":["javascript","pushstate","html5","static","server"],"install":[{"cmd":"npm install pushstate-server","lang":"bash","label":"npm"},{"cmd":"yarn add pushstate-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add pushstate-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a CommonJS module. Direct ESM imports are not supported without a transpilation step or dynamic import.","wrong":"import server from 'pushstate-server';","symbol":"server","correct":"const server = require('pushstate-server');"},{"note":"The `start` function is a method of the exported `server` object, not a named export itself.","wrong":"import { start } from 'pushstate-server';","symbol":"start","correct":"const server = require('pushstate-server');\nserver.start({ port: 3000, directory: './public' });"}],"quickstart":{"code":"const server = require('pushstate-server');\n\n// Start a server for a single directory\nserver.start({\n  port: process.env.PORT ?? 3000,\n  directory: './public'\n});\n\nconsole.log(`Server started on port ${process.env.PORT ?? 3000} serving './public'.`);\nconsole.log('Access your single-page app at http://localhost:3000');\nconsole.log('e.g., http://localhost:3000/some/pushstate/route will serve index.html');\n\n// Or for multiple directories\n// server.start({\n//   port: process.env.ANOTHER_PORT ?? 4200,\n//   directories: ['./dist', './node_modules']\n// });","lang":"javascript","description":"Demonstrates how to initialize and start the pushstate-server for serving static files from a single directory."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The 'pushstate-server' package has not been installed or is not accessible in the current project environment.","error":"Error: Cannot find module 'pushstate-server'"},{"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.","cause":"The specified port (e.g., 3000) is already being used by another process on your system.","error":"EADDRINUSE: address already in use :::3000"},{"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.","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.","error":"Client-side `history.pushState()` or `history.replaceState()` does not correctly load content after browser refresh."}],"ecosystem":"npm"}