Registry / web-framework / http-server-spa

http-server-spa

library1.3.0jsnpmunverified

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.

web-framework devops

npm install http-server-spa

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-SERVER-SPA

http-server-spa

web-frameworkjavascriptv1.3.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.

✓ N/A - Primarily a CLI tool. No public programmatic API is exported.

✗ const server = require('http-server-spa');

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.

HttpServerSpa

✓ N/A - No named exports.

✗ import { HttpServerSpa } from 'http-server-spa';

The package does not export specific classes or functions for library usage. It functions solely as a command-line executable, typically installed globally.

default

✓ N/A - No default export.

✗ import httpServerSpa from 'http-server-spa';

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.

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.

// To get started, first ensure Node.js is installed. // 1. Install http-server-spa globally using npm: // npm install -g http-server-spa // 2. Create a directory for your Single Page Application (SPA): // mkdir my-spa-app // cd my-spa-app // 3. Create a basic 'index.html' file which will act as your SPA's entry point // and the fallback file: // echo '<!DOCTYPE html>\n<html>\n<head>\n <title>My SPA</title>\n <style>body { font-family: sans-serif; text-align: center; margin-top: 50px; }</style>\n</head>\n<body>\n <h1>Welcome to my SPA!</h1>\n <div id="app"></div>\n <script>\n document.getElementById("app").innerHTML = "Current path: <b>" + window.location.pathname + "</b>";\n // Basic client-side router simulation for demonstration window.onpopstate = () => { console.log('Path changed to:', window.location.pathname); document.getElementById("app").innerHTML = "Current path: <b>" + window.location.pathname + "</b>"; }; </script>\n</body>\n</html>' > index.html // 4. Optionally, create a static asset, e.g., a CSS file: // mkdir assets // echo 'body { background-color: #f0f0f0; }' > assets/style.css // 5. Start the http-server-spa. This command serves the current directory ('.'), // uses 'index.html' as the fallback for all non-file routes, and listens on port 8080. // Open your terminal in the 'my-spa-app' directory and run: // http-server-spa . index.html 8080 // After running the command, open your web browser and navigate to: // - http://localhost:8080/ (serves index.html, status 200) // - http://localhost:8080/about (serves index.html, status 301, client-side router handles path) // - http://localhost:8080/user/profile (serves index.html, status 301, client-side router handles path) // - http://localhost:8080/assets/style.css (serves the actual CSS file, status 200) // Press Ctrl+C in the terminal to stop the server.

http-server-spa --version

Debug

Known issues

breakingUsing `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.

fix

Upgrade to `http-server-spa` version 3.2.0 or newer: `npm install -g http-server-spa@latest`.

affects: <3.2.0

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

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.

affects: >=1.0.0

gotchaThe `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.

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.

affects: >=1.0.0

Errors

Common errors & fixes

http-server-spa: command not found

The `http-server-spa` executable is not found in the system's PATH.

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.

Error: ENOENT: no such file or directory, stat '<path>'

The specified directory to serve or the fallback HTML file does not exist at the given path.

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.

My SPA routes are returning a 301 (Moved Permanently) status instead of 200 (OK).

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.

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.

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/lukejacksonn/http-server-spa ↗

packagehttps://www.npmjs.com/package/http-server-spa ↗