GitHub - JavaScriptSolidServer/jsserve: Static file server with REST write support

servejss

Static file server with REST write support. A drop-in npx serve alternative.

Why?

npx serve is great for quickly serving static files, but it's read-only. Sometimes you need to:

Upload files during development
Test REST APIs locally
Sync files between devices on your LAN
Have a simple WebDAV-like server

servejss is serve with superpowers: same simple interface, but you can write too.

Install

Or use directly with npx:

Usage

# Serve current directory (read + write enabled)
servejss

# Serve specific directory
servejss ./public

# Custom port
servejss -p 8080

# Specify port and directory
servejss -l 3000 ./dist

# Read-only mode (exactly like npx serve)
servejss --read-only

Output

 servejss

  Directory:  /home/user/project

  Local:      http://localhost:3000
  Network:    http://192.168.1.5:3000

  Mode:       GET/PUT/DELETE enabled

  Press Ctrl+C to stop

REST API

# Read a file
curl http://localhost:3000/file.txt

# Create or update a file
curl -X PUT -d "Hello, World!" http://localhost:3000/file.txt

# Delete a file
curl -X DELETE http://localhost:3000/file.txt

# Conditional update (only if ETag matches)
curl -X PUT -H 'If-Match: "abc123"' -d "Updated" http://localhost:3000/file.txt

# Create only if doesn't exist
curl -X PUT -H 'If-None-Match: *' -d "New file" http://localhost:3000/new.txt

Options

Usage: servejss [options] [directory]

Options:
  -v, --version            Output version number
  -l, --listen <uri>       Specify a URI endpoint on which to listen
  -p, --port <port>        Specify custom port (default: 3000)
  -H, --host <host>        Host to bind to (default: 0.0.0.0)
  -s, --single             Rewrite all not-found requests to index.html (SPA mode)
  -d, --debug              Show debugging information
  -C, --cors               Enable CORS (enabled by default)
  -L, --no-request-logging Do not log any request information
  --no-etag                Disable ETag generation
  -S, --symlinks           Resolve symlinks instead of showing 404
  --ssl-cert <path>        Path to SSL certificate
  --ssl-key <path>         Path to SSL private key
  --no-port-switching      Do not open a different port if specified one is taken
  -r, --read-only          Disable PUT/DELETE methods (like npx serve)
  --auth <credentials>     Enable basic auth (user:pass)
  --solid                  Enable full Solid protocol features
  -q, --quiet              Suppress all output
  -h, --help               Display help

Comparison with serve

Feature	serve	servejss
Static file serving	✅	✅
Directory listings	✅	✅
CORS	✅	✅
SPA mode	✅	✅
Custom port	✅	✅
Auto port switching	✅	✅
SSL/TLS	✅	✅
PUT (create/update)	❌	✅
DELETE	❌	✅
ETags	❌	✅
Conditional requests	❌	✅
Upgrade to Solid	❌	✅

Advanced Features

Conditional Requests

servejss supports ETags for efficient caching and safe concurrent updates:

# Get a file with its ETag
curl -i http://localhost:3000/file.txt
# Returns: ETag: "a1b2c3"

# Only fetch if changed
curl -H 'If-None-Match: "a1b2c3"' http://localhost:3000/file.txt
# Returns: 304 Not Modified (if unchanged)

# Safe update (fails if file changed since you read it)
curl -X PUT -H 'If-Match: "a1b2c3"' -d "new content" http://localhost:3000/file.txt

Upgrade to Solid

servejss is powered by JSS (JavaScript Solid Server). Enable full Solid protocol support:

This enables:

Solid-OIDC authentication
Web Access Control (WAC)
Linked Data support (Turtle, JSON-LD)
WebID profiles

Use Cases

Local Development Server

# Serve your project with write support for uploads
cd my-project
servejss

Quick File Sharing on LAN

# Share files with devices on your network
servejss --read-only ~/shared-files

REST API Testing

# Mock a simple REST backend
servejss ./mock-data

WebDAV Alternative

# Lightweight file sync server
servejss --auth user:pass ~/sync

License

MIT

Related Projects

JSS - Full Solid server
serve - Static file serving (read-only)