tessl/npm-st

A module for serving static files with etags, caching, gzip compression, CORS support, and directory indexing.

—

Pending

Overview

Eval results

Files

CLI Interface

Name: tessl/npm-st
Author: tessl

Command-line interface for running st as a standalone HTTP server with extensive configuration options and built-in help system.

Capabilities

Command Line Usage

The st CLI provides a full-featured HTTP server for serving static files.

st [options]

# Basic usage examples:
st                           # Serve current directory on port 1337
st -p 8080                   # Serve on port 8080
st -d ./public               # Serve ./public directory
st -d ./static -u /assets    # Serve ./static at /assets URL

Usage Examples:

# Basic server
st

# Custom port and directory
st -p 3000 -d ./website

# Development server with CORS
st -p 8080 -d ./dist --cors

# Production-like server
st -p 80 -d /var/www/html --no-dot -a 3600000

# Local development with custom URL mount
st -d ./build -u /app -p 3000 --localhost

Port Configuration

Configure the HTTP server port.

-p, --port PORT     # Listen on PORT (default: 1337)

Usage Examples:

# Default port (1337)
st

# Custom port
st -p 8080
st --port 3000

# Use environment variable (PORT=8080 st)
PORT=8080 st

Host Configuration

Configure the server bind address.

-H, --host HOST     # Bind address HOST (default: * - all interfaces)
-l, --localhost     # Same as "--host localhost"

Usage Examples:

# Bind to all interfaces (default)
st

# Bind to specific IP
st -H 192.168.1.100

# Bind to localhost only (secure for development)  
st -l
st --localhost

# Bind to specific hostname
st --host example.local

Directory and URL Configuration

Configure which directory to serve and URL mount point.

-d, --dir DIRECTORY    # Serve the contents of DIRECTORY (default: current working directory)
-u, --url /url         # Serve at this mount url (default: /)

Usage Examples:

# Serve current directory (default)
st

# Serve specific directory
st -d ./public
st --dir /var/www/html

# Serve with URL mount point
st -d ./static -u /static
st --dir ./assets --url /assets

# Complex example: serve ./build at /app
st -d ./build -u /app -p 3000

Directory Indexing

Configure directory listing and index file behavior.

-i, --index [INDEX]    # Use the specified INDEX filename as the result when a directory 
                       # is requested. Set to "true" to turn autoindexing on, or "false" 
                       # to turn it off. If no INDEX is provided, then it will turn 
                       # autoindexing on. (default: true)
-ni, --no-index        # Same as "--index false"

Usage Examples:

# Auto-indexing enabled (default)
st

# Use specific index file
st -i index.html
st --index home.htm

# Enable auto-indexing explicitly
st -i true
st --index

# Disable directory access
st -ni
st --no-index
st --index false

Dot File Access

Configure access to dot files (hidden files starting with .).

-., --dot [DOT]       # Allow .files to be served. Set to "false" to disable.
-n., --no-dot         # Same as "--dot false"

Usage Examples:

# Block dot files (default)
st

# Allow dot files
st -.
st --dot
st --dot true

# Explicitly block dot files
st -n.
st --no-dot
st --dot false

CORS Configuration

Configure Cross-Origin Resource Sharing headers.

-co, --cors           # Enable CORS to serve files to any domain

Usage Examples:

# No CORS headers (default)
st

# Enable CORS
st --cors
st -co

# CORS with other options
st -d ./api-docs --cors -p 8080

Cache Configuration

Configure caching behavior and cache expiration.

-nc, --no-cache       # Turn off all caching
-a, --age AGE         # Max age (in ms) of cache entries

Usage Examples:

# Default caching enabled
st

# Disable all caching
st --no-cache
st -nc

# Custom cache age (1 hour = 3600000ms)
st -a 3600000
st --age 1800000  # 30 minutes

# Development with no caching
st -d ./src --no-cache --cors

# Production with long cache
st -d ./build -a 86400000  # 24 hours

Help and Information

Display help information and command usage.

-h, --help            # Show help information

Usage Examples:

# Show help
st -h
st --help

# Help output includes:
# - Command description
# - All available options
# - Default values
# - Usage examples

Complete Examples

Real-world usage scenarios combining multiple options.

Development Server:

# Local development with live reloading-friendly settings
st -d ./src -p 3000 --localhost --no-cache --cors

Production Server:

# Production server with security and performance optimizations
st -d /var/www/html -p 80 --no-dot -a 3600000 -ni

Static Site Hosting:

# Host static site with proper indexing
st -d ./dist -p 8080 -i index.html

API Documentation Server:

# Serve API docs with CORS for external access
st -d ./api-docs -p 4000 --cors -i index.html

Asset Server:

# Dedicated asset server with long cache times
st -d ./assets -u /assets -p 9000 -a 31536000000  # 1 year cache

Secure Local Server:

# Secure server for sensitive files
st -d ./private --localhost -p 8443 --no-dot --no-index

Environment Variables

The CLI respects certain environment variables.

PORT=1337             # Default port if -p/--port not specified

Usage Examples:

# Set default port via environment
export PORT=8080
st  # Will use port 8080

# Override environment with flag
PORT=8080 st -p 3000  # Will use port 3000

# Use in Docker/deployment scenarios
docker run -e PORT=80 -p 80:80 my-app

# Temporary environment variable
PORT=9000 st -d ./build

Server Information

The CLI displays connection information when the server starts.

# Server startup message format:
listening at http://HOST:PORT

# Examples:
listening at http://localhost:1337
listening at http://192.168.1.100:8080
listening at http://[::1]:3000  # IPv6

Error Handling

The CLI handles various error conditions with appropriate exit codes and messages.

Common Errors:

Invalid port number
Invalid age value
Directory not found
Permission denied
Port already in use

Usage Examples:

# Invalid port
st -p abc
# Error: invalid port: abc

# Invalid age  
st -a xyz
# Error: invalid age: "xyz"

# Non-existent directory
st -d /nonexistent
# Server will fail to start with filesystem error

Install with Tessl CLI