{"id":14624,"library":"http-server-spa","title":"HTTP Server for Single Page Applications","description":"http-server-spa is a lightweight and fast Node.js-based static file server specifically designed to host Single Page Applications (SPAs). Its primary feature is built-in support for the HTML5 History API fallback, which routes all non-file requests to a specified fallback HTML file (e.g., `index.html`), allowing client-side routers to handle URL paths without 404 errors. This differentiates it from general-purpose static servers that require additional configuration for this behavior. The package is predominantly a command-line interface (CLI) tool, commonly installed globally. While the npm metadata indicates version 1.3.0, the most recent \"first official release\" is tagged as 3.2.0, addressing several bug fixes including Node.js compatibility. Release cadence appears irregular, focusing on critical bug fixes and improvements rather than a fixed schedule. It distinguishes between \"file requests\" and \"route requests,\" serving actual files with a 200 status or redirecting route requests to the fallback with a 301 status for non-root paths.","status":"active","version":"1.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/lukejacksonn/http-server-spa","tags":["javascript"],"install":[{"cmd":"npm install http-server-spa","lang":"bash","label":"npm"},{"cmd":"yarn add http-server-spa","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-server-spa","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is not designed for programmatic consumption; its main entry point is for CLI argument parsing and server instantiation rather than exposing a library API.","wrong":"const server = require('http-server-spa');","symbol":"*","correct":"N/A - Primarily a CLI tool. No public programmatic API is exported."},{"note":"The package does not export specific classes or functions for library usage. It functions solely as a command-line executable, typically installed globally.","wrong":"import { HttpServerSpa } from 'http-server-spa';","symbol":"HttpServerSpa","correct":"N/A - No named exports."},{"note":"There is no default export. Attempting to import the module directly will typically yield an empty object or undefined, as it's not intended for programmatic module import.","wrong":"import httpServerSpa from 'http-server-spa';","symbol":"default","correct":"N/A - No default export."}],"quickstart":{"code":"// To get started, first ensure Node.js is installed.\n\n// 1. Install http-server-spa globally using npm:\n// npm install -g http-server-spa\n\n// 2. Create a directory for your Single Page Application (SPA):\n// mkdir my-spa-app\n// cd my-spa-app\n\n// 3. Create a basic 'index.html' file which will act as your SPA's entry point\n// and the fallback file:\n// echo '\\n\\n\\n My SPA\\n \\n\\n\\n

Welcome to my SPA!

\\n

\\n \\n\\n' > index.html\n\n// 4. Optionally, create a static asset, e.g., a CSS file:\n// mkdir assets\n// echo 'body { background-color: #f0f0f0; }' > assets/style.css\n\n// 5. Start the http-server-spa. This command serves the current directory ('.'),\n// uses 'index.html' as the fallback for all non-file routes, and listens on port 8080.\n// Open your terminal in the 'my-spa-app' directory and run:\n// http-server-spa . index.html 8080\n\n// After running the command, open your web browser and navigate to:\n// - http://localhost:8080/ (serves index.html, status 200)\n// - http://localhost:8080/about (serves index.html, status 301, client-side router handles path)\n// - http://localhost:8080/user/profile (serves index.html, status 301, client-side router handles path)\n// - http://localhost:8080/assets/style.css (serves the actual CSS file, status 200)\n\n// Press Ctrl+C in the terminal to stop the server.","lang":"javascript","description":"This quickstart demonstrates how to globally install `http-server-spa` and use its CLI to serve a basic single-page application, showcasing the history-api-fallback functionality for client-side routing and serving static assets."},"warnings":[{"fix":"Upgrade to `http-server-spa` version 3.2.0 or newer: `npm install -g http-server-spa@latest`.","message":"Using `http-server-spa` versions older than 3.2.0 with Node.js environments that do not support ES2017 `try/catch` syntax (e.g., Node.js versions prior to 7.6) may lead to runtime errors or server crashes due to syntax incompatibilities. Version 3.2.0 fixed this by using a more widely compatible syntax.","severity":"breaking","affected_versions":"<3.2.0"},{"fix":"Understand that the 301 status for non-root routes is intentional, indicating that the client-side router should handle the path after the redirect. Ensure your client-side application is robust to this redirect behavior.","message":"When serving a SPA, `http-server-spa` responds to 'route requests' (paths without a file extension) with a HTTP 301 Redirect status for non-root paths (e.g., `/user/profile` redirects to `index.html` with a 301). The root path (`/`) correctly responds with a 200 OK. This 301 behavior for routes can sometimes be unexpected if you anticipate all fallback responses to be 200 OK.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you install the package globally via `npm install -g http-server-spa` or add the local `node_modules/.bin` directory to your system's PATH if you prefer a local installation.","message":"The `http-server-spa` package is primarily a command-line interface (CLI) tool and is typically installed globally (`npm install -g http-server-spa`). If it's installed locally or not in your system's PATH, the `http-server-spa` command will not be found.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the package globally using `npm install -g http-server-spa`. If already installed globally, ensure your npm global bin directory is in your system's PATH.","cause":"The `http-server-spa` executable is not found in the system's PATH.","error":"http-server-spa: command not found"},{"fix":"Verify that the first argument (directory path) and the second argument (fallback HTML file path) provided to `http-server-spa` correctly point to existing locations relative to where the command is executed, or absolute paths.","cause":"The specified directory to serve or the fallback HTML file does not exist at the given path.","error":"Error: ENOENT: no such file or directory, stat ''"},{"fix":"This is not an error to be fixed in the server, but an intended feature. Your client-side SPA router should be designed to handle these redirects and process the URL path on the client side after the initial page load.","cause":"This is the intended behavior for `http-server-spa` for non-root 'route requests'. The server sends a 301 redirect to the fallback HTML file.","error":"My SPA routes are returning a 301 (Moved Permanently) status instead of 200 (OK)."}],"ecosystem":"npm"}