Single Page App Development Server

1.12.0 verified Sun Apr 19 auth: no javascript

angular-http-server is a lightweight command-line interface (CLI) development server designed specifically for Single Page Applications (SPAs) such as those built with Angular, React, or Vue. Its primary function is to serve static assets while routing all non-existent file requests back to the application's `index.html` file, enabling client-side routing without 404 errors. Currently at version 1.12.0, it is actively maintained and provides essential features for local development like custom port assignment, automatic browser opening, HTTPS with self-signed certificates, CORS enablement, and a basic HTTP proxy. It explicitly states it is not intended for production use, focusing solely on streamlining the development workflow by abstracting away complex server configurations for SPA development.

Common errors

error angular-http-server: command not found ↓

cause The `angular-http-server` package was not installed globally or its executable path is not in your system's PATH environment variable.

fix

Run npm install -g angular-http-server to install the package globally, making the command available.

error Error: Could not locate index.html ↓

cause The server could not find the primary `index.html` file in the directory it was started from, or in the path specified by `--path` or `--rootFile`.

fix

Ensure you are running the command from your SPA's build output directory (e.g., dist/). Alternatively, use --path <directory> to point to the correct folder or --rootFile <filename.html> if your entry file is named differently.

error Browser security warning: 'Your connection is not private' / 'NET::ERR_CERT_AUTHORITY_INVALID' ↓

cause You are using the `--https` flag which generates a self-signed SSL certificate, which is not trusted by web browsers by default.

fix

For development, you can proceed by accepting the risk in your browser. For production-like trusted SSL, configure custom certificates using --key path/to/key.pem and --cert path/to/cert.pem.

Warnings

gotcha This server is explicitly designed for development and testing purposes only and makes no claims to be a production server. Using it in production environments is not recommended and unsupported. ↓

fix For production deployments, utilize a robust web server like Nginx, Apache, or a Node.js-based solution like Express.js with a reverse proxy, designed for security, performance, and scalability.

gotcha Enabling HTTPS with `--https` or `--ssl` generates a self-signed certificate, which will cause web browsers to display security warnings. This is intended for development and local testing only. ↓

fix For a trusted HTTPS connection, provide your own valid SSL certificate and key using the `--key` and `--cert` flags, or accept the security risk in your browser during local development.

gotcha When using a configuration file alongside command-line arguments, CLI options always take precedence and will override any conflicting settings specified in the config file. ↓

fix Be aware of this hierarchy. To ensure config file settings are used, avoid overriding them with CLI flags. To debug, check `angular-http-server --help` for flag names and their defaults.

gotcha The package must be installed globally (`npm install -g`) to be used as a command-line tool. It is not designed for programmatic `import` or `require` within other Node.js applications. ↓

fix Ensure global installation. If you need a programmatic HTTP server for your application, consider alternatives like `http-server` or `serve`.

Install

npm install angular-http-server

yarn add angular-http-server

pnpm add angular-http-server

Imports

angular-http-server CLI command
wrong
```
import angularHttpServer from 'angular-http-server'; // Incorrect, this is a CLI tool.
```
correct
```
npm install -g angular-http-server
# Then, navigate to your SPA's build directory and run:
angular-http-server
```
This package is a CLI tool and not intended for programmatic JavaScript/TypeScript import or usage. Its primary interaction is via global command line installation and execution.
Configuration options via CLI flags
wrong
```
angular-http-server port=8080 open=true https=true // Incorrect syntax for flags.
```
correct
```
angular-http-server -p 8080 --open --https
```
Configuration options are passed as command-line flags (e.g., `-p` or `--port`) or via a config file, not as JavaScript object literals directly on the command line.
Configuration via file
wrong
```
require('./my-server.config.js'); // Incorrect, the CLI loads the config file.
```
correct
```
angular-http-server --config my-server.config.js
```
A JavaScript config file can export an object of parameters or a function to dynamically configure the server. The `--config` flag tells the CLI to load this file; it's not loaded directly in userland JS.

Quickstart

Demonstrates global installation and starting the server with common development options like custom port, auto-open, HTTPS, and CORS.

# Install angular-http-server globally to make it available as a command.
# This is typically a one-time setup for development.
npm install -g angular-http-server

# Navigate into your Single Page Application's build output directory.
# This is usually the 'dist' folder generated by your build process (e.g., Angular CLI, Webpack).
cd /path/to/your/project/dist

# Start the server with common development options:
# -p 8080: Specifies port 8080.
# --open: Automatically opens the application in your default web browser.
# --https: Enables HTTPS with a self-signed certificate for local development.
# --cors: Enables Cross-Origin Resource Sharing.
angular-http-server -p 8080 --open --https --cors

# If your 'index.html' is not directly in the current directory,
# or you need to serve from a sub-path, use --path:
# angular-http-server --path my-app-build-folder -p 4200