HTTP Server for Single Page Applications

Common errors

• http-server-spa: command not found

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

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

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

Warnings

• breaking 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.
  Fix: Upgrade to `http-server-spa` version 3.2.0 or newer: `npm install -g http-server-spa@latest`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install http-server-spa npm
• yarn add http-server-spa yarn
• pnpm add http-server-spa pnpm

Imports

• *
  wrong:

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

  correct:

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

  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
  wrong:

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

  correct:

  N/A - No named exports.

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

  import httpServerSpa from 'http-server-spa';

  correct:

  N/A - No default export.

  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.

Quickstart

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.