@scom/serve

A simple HTTP/HTTPS static file server built with Node.js built-in modules only. No external dependencies required.

Features

• ✅ HTTP and HTTPS support
• ✅ Static file serving with proper MIME types
• ✅ Directory listing when no index file is found
• ✅ CORS support (enabled by default)
• ✅ Cache headers
• ✅ Automatic browser opening
• ✅ Cross-platform compatibility
• ✅ Zero external dependencies

Installation

npm install @scom/serve

Usage

Command Line

# Serve current directory on 0.0.0.0:8080
npx @scom/serve

# Serve specific directory on custom port
npx @scom/serve dist -p 3000

# HTTPS server with SSL certificates
npx @scom/serve -p 8443 -s --cert cert.pem --key key.pem

# Open browser automatically after starting
npx @scom/serve --open

# Run in silent mode (suppress log output)
npx @scom/serve --silent

# Map URL paths to local directories
npx @scom/serve --map /dist:./dist --map /assets:../assets

# Disable CORS and gzip compression
npx @scom/serve --no-cors --no-gzip

# Custom cache settings
npx @scom/serve --cache 7200

# Serve on specific host and port
npx @scom/serve -H 127.0.0.1 -p 9000

Programmatic API

import { StaticServer, createServer } from '@scom/serve';

// Using the class with basic options
const server = new StaticServer({
  port: 3000,
  root: './dist',
  open: true
});

await server.start();

// Using the factory function with advanced options
const server2 = createServer({
  port: 8080,
  host: '0.0.0.0',
  cors: true,
  cache: 3600,
  gzip: true,
  staticMaps: {
    '/api': './mock-api',
    '/assets': '../shared-assets'
  }
});

await server2.start();

// HTTPS server with SSL certificates
const httpsServer = new StaticServer({
  port: 8443,
  https: true,
  cert: './certs/server.crt',
  key: './certs/server.key',
  silent: true
});

await httpsServer.start();

CLI Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --port | -p | Port number for the server to listen on | 8080 | | --host | -H | Hostname or IP address to bind the server to | 0.0.0.0 | | --root | -r | Root directory to serve static files from | Current directory | | --https | -s | Enable HTTPS/SSL encryption (requires --cert and --key) | false | | --cert | | Path to SSL/TLS certificate file for HTTPS connections | | | --key | | Path to SSL/TLS private key file for HTTPS connections | | | --open | -o | Automatically open the served URL in default web browser | false | | --silent | -S | Suppress log output and run in quiet mode | false | | --no-cors | | Disable Cross-Origin Resource Sharing (CORS) headers | CORS enabled | | --cache | | Set Cache-Control max-age header value in seconds | 3600 | | --no-gzip | | Disable gzip compression for served files | gzip enabled | | --map | | Map URL paths to local directories (format: /url:./local/path) | | | --help | -h | Display help information with usage and available options | | | --version | -v | Show the current version of the @scom/serve package | |

API Options

interface ServeOptions {
  port?: number;          // Port number for the server to listen on (default: 8080)
  host?: string;          // Hostname or IP address to bind to (default: '0.0.0.0')
  root?: string;          // Root directory to serve static files from (default: process.cwd())
  https?: boolean;        // Enable HTTPS/SSL encryption (default: false)
  cert?: string;          // Path to SSL/TLS certificate file for HTTPS connections
  key?: string;           // Path to SSL/TLS private key file for HTTPS connections
  cors?: boolean;         // Enable Cross-Origin Resource Sharing headers (default: true)
  open?: boolean;         // Automatically open the served URL in default browser (default: false)
  silent?: boolean;       // Suppress log output and run in quiet mode (default: false)
  cache?: number;         // Cache-Control max-age header value in seconds (default: 3600)
  gzip?: boolean;         // Enable gzip compression for served files (default: true)
  staticMaps?: Record<string, string>; // Map URL paths to local directories
}
}

Supported MIME Types

The server automatically detects and serves files with appropriate MIME types for:

• HTML files (.html, .htm)
• JavaScript files (.js)
• CSS files (.css)
• JSON files (.json)
• Images (.png, .jpg, .gif, .ico, .svg)
• Fonts (.woff, .woff2, .ttf, .eot)
• Media files (.mp4, .webm, .mp3, .wav, .ogg)
• Documents (.pdf, .txt, .xml, .zip)

Directory Listing

When a directory is accessed and no index file (index.html, index.htm, default.html) is found, the server generates a clean, sortable directory listing.

HTTPS Support

To enable HTTPS, provide both certificate and key files:

npx @scom/serve -s --cert path/to/cert.pem --key path/to/key.pem

CORS Support

CORS is enabled by default with permissive headers. To disable CORS:

npx @scom/serve --no-cors

Testing

The package includes comprehensive tests covering:

• Core server functionality
• CLI interface
• Performance characteristics
• Error handling
• Concurrent request handling

# Run all tests
npm test

# Run specific test suites
npm run test:server      # Core server tests
npm run test:cli         # CLI tests  
npm run test:performance # Performance tests

Development

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

# Run tests during development
npm run test:watch