testing-https-server

HTTPS Server

A simple HTTPS static file server with built-in self-signed certificates for testing purposes. Similar to http-server but provides HTTPS functionality out of the box.

Features

• 🔒 Built-in HTTPS: Self-signed certificates included for immediate testing
• 📁 Static File Serving: Serves any directory with automatic index.html detection
• 🌐 CORS Support: Enable/disable CORS headers as needed
• 💾 Caching Control: Configurable cache headers
• 🎨 Colored Output: Beautiful console output with status information
• 🚀 SPA Support: Fallback to index.html for single-page applications
• 🛑 Graceful Shutdown: Clean server shutdown on SIGINT/SIGTERM

Installation

npm install

Usage

Command Line

# Serve current directory on default port (8443)
npx https-server

# Serve specific directory
npx https-server ./public

# Custom port
npx https-server -p 9000

# Enable caching for 1 hour
npx https-server -c 3600

# Disable CORS
npx https-server --no-cors

# Bind to different address
npx https-server -a 0.0.0.0

# Silent mode (minimal output)
npx https-server -s

# Open browser automatically (requires 'opener' package)
npx https-server -o

Programmatic Usage

const HttpsServer = require('./index');

const server = new HttpsServer({
  port: 8443,
  directory: './public',
  host: 'localhost',
  cors: true,
  cache: 3600
});

server.start()
  .then(() => {
    console.log('Server started successfully!');
  })
  .catch((err) => {
    console.error('Failed to start server:', err);
  });

Options

Option	Short	Default	Description
--port	-p	8443	Port to listen on
--address	-a	localhost	Address to bind to
--cache	-c	-1	Cache time in seconds (-1 disables caching)
--no-cors			Disable CORS headers
--open	-o		Open browser after starting
--silent	-s		Suppress log messages
--help	-h		Show help information

Security Warning

⚠️ Important: This server uses self-signed certificates for testing purposes only.

When you visit https://localhost:8443 (or your chosen port), your browser will show a security warning. This is expected behavior. To proceed:

• Click "Advanced" (Chrome) or "Advanced..." (Firefox)
• Click "Proceed to localhost (unsafe)" or "Accept the Risk and Continue"

Never use these certificates in production!

Examples

Basic Static Site

# Create some test files
mkdir my-site
echo '<h1>Hello HTTPS!</h1>' > my-site/index.html
echo '<h2>About Page</h2>' > my-site/about.html

# Serve the site
npx https-server my-site

# Visit https://localhost:8443

Single Page Application

# For SPAs, all routes will fallback to index.html
npx https-server ./dist

# Perfect for React, Vue, Angular apps

Development with Hot Reload

# Enable caching for assets but not HTML
npx https-server -c 0 ./build

Public Access

# Bind to all interfaces (be careful!)
npx https-server -a 0.0.0.0 -p 8443

API Reference

HttpsServer Class

Constructor Options

{
  port: 8443,           // Port number
  directory: '.',       // Directory to serve
  host: 'localhost',    // Host to bind to
  cors: true,           // Enable CORS headers
  cache: -1             // Cache time in seconds (-1 = no cache)
}

Methods

• start() - Returns a Promise that resolves when server starts
• stop() - Returns a Promise that resolves when server stops gracefully

Troubleshooting

Port Already in Use

# Check what's using the port
npx https-server -p 9000

Permission Denied (Ports < 1024)

# Use a port > 1024 or run with sudo (not recommended)
npx https-server -p 8443

Browser Won't Accept Certificate

• Try in incognito/private browsing mode
• Clear browser cache and cookies
• Make sure you're accessing via https:// not http://

License

MIT

Contributing

• Fork the repository
• Create your feature branch
• Commit your changes
• Push to the branch
• Create a Pull Request

Happy serving! 🚀