Static File Serving Standards

Load this skill when configuring MIME types, selecting compression formats, setting cache headers, organizing static file directories, or optimizing file delivery with SWS.

When to load: documenting or reviewing compression setup, cache-control strategy, MIME-type overrides, SPA vs. multi-page file layout, directory listing, or pre-compression build steps.

General Principles

• Serve the right Content-Type: SWS uses mime_guess to determine MIME types from file extensions. If the wrong type is served, rename the file or add a custom header rule
• Compress where it helps: Text-based formats compress well (HTML, CSS, JS, JSON, SVG, XML). Pre-compress at build time for zero-CPU serving
• Cache aggressively for versioned assets: Use fingerprinting in filenames (app.a1b2c3d.js) with Cache-Control: max-age=31536000 (1 year)
• Don't cache HTML entry points: HTML files that reference versioned assets should have short or no cache TTL
• Use a CDN for production: Put SWS behind a CDN (Cloudflare, Fastly, CloudFront) for edge caching and DDoS protection

MIME Types

SWS determines Content-Type from file extension. Ensure files have correct extensions:

Extension	MIME Type	Category
.html, .htm	text/html	Document
.css	text/css	Stylesheet
.js, .mjs	text/javascript (or application/javascript)	Script
.json	application/json	Data
.xml	application/xml	Data
.svg	image/svg+xml	Vector image
.png	image/png	Raster image
.jpg, .jpeg	image/jpeg	Raster image
.webp	image/webp	Raster image
.avif	image/avif	Raster image
.gif	image/gif	Raster image
.ico	image/x-icon	Icon
.woff2	font/woff2	Web font
.woff	font/woff	Web font
.pdf	application/pdf	Document
.wasm	application/wasm	WebAssembly
.txt	text/plain	Text
.md	text/markdown	Markdown
.zip	application/zip	Archive
.tar	application/x-tar	Archive
.gz	application/gzip	Compressed
.br	application/brotli	Compressed
.zst	application/zstd	Compressed

Custom MIME Types

Use the TOML config file to override or add MIME types for specific paths:

[advanced.headers]
source = "**/*.yaml"
headers = { Content-Type = "application/yaml" }

Compression

Static (Pre-compressed) Compression

Pre-compress files at build time. SWS serves .br, .gz, or .zst variants automatically based on the client's Accept-Encoding header:

Variant	Extension	Encoding Header	Build Command
Brotli	.br	br	brotli -q 11 -f file
Gzip	.gz	gzip	gzip -9 -k file
Zstandard	.zst	zstd	zstd -19 -k file

Compression ratios (typical for text files):

Format	Level	Ratio	Speed
Brotli	11	~75%	Slowest
Zstandard	19	~72%	Medium
Gzip	9	~68%	Fastest

Dynamic (On-the-fly) Compression

SWS compresses responses in real-time when the client sends Accept-Encoding and no pre-compressed variant exists:

• Only text-based MIME types are compressed (HTML, CSS, JS, JSON, XML, SVG, etc.)
• Responses below 860 bytes skip compression (overhead exceeds savings)
• Compression level is configurable: fastest, default, best

SWS CLI Examples

# Serve with Brotli pre-compressed variants only (no on-the-fly compression)
static-web-server --root ./dist --compression-static --compression=false

# Serve with both pre-compressed variants and on-the-fly gzip fallback
static-web-server --root ./dist --compression-static --compression

# Serve with only on-the-fly compression at fastest level
static-web-server --root ./dist --compression --compression-level fastest

Caching Strategy

Cache-Control Headers

SWS sets Cache-Control based on file extension. Enable with --cache-control-headers (default: enabled):

Category	Extensions	max-age
Static assets	.css, .js, .png, .woff2, .avif, .webp, .pdf, .ico, .gz, .bz2, .zip, .tar	1 year (31536000)
Data/feeds	.json, .xml, .rss, .atom	1 hour (3600)
Everything else	unknown extensions	1 hour (3600)

Custom Cache Headers

Override Cache-Control for specific paths via TOML:

[advanced.headers]
source = "**/*.html"
headers = { Cache-Control = "no-cache" }

Versioned Assets Pattern

For production deployments, use content-hash filenames and cache aggressively:

dist/
  index.html              ← short cache (or no-cache)
  assets/
    app.a1b2c3d.js        ← 1-year cache (fingerprinted)
    style.e4f5g6h.css     ← 1-year cache (fingerprinted)
    logo.h7i8j9k.png      ← 1-year cache (fingerprinted)

This way, when app.a1b2c3d.js changes, the new filename app.x9y0z1.js triggers a fresh download. The HTML entry point changes to reference the new filename.

Security Headers for Static Sites

Enable --security-headers (auto-enabled with --tls) for production static sites:

static-web-server \
    --root ./dist \
    --tls --tls-cert cert.pem --tls-key key.pem \
    --security-headers \
    --cache-control-headers

Headers sent: Strict-Transport-Security, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Content-Security-Policy: frame-ancestors 'self', Referrer-Policy: strict-origin-when-cross-origin.

File Organization

Single-Page Application (SPA)

dist/
  index.html              ← entry point (served for all routes)
  assets/
    app.js
    style.css
  favicon.ico
  robots.txt

SWS configuration:

static-web-server --root ./dist --page-fallback ./index.html

The --page-fallback option serves index.html for any 404, enabling client-side routing.

Multi-Page Static Site

dist/
  index.html
  about.html
  blog/
    index.html
    post-1.html
  assets/
    main.css
    main.js
  images/
    hero.png

SWS configuration:

static-web-server --root ./dist --index-files "index.html,index.htm"

Directory Listing (Development)

For development or internal tools, enable directory listing:

static-web-server --root ./public --directory-listing

Options: --directory-listing-order (0–6), --directory-listing-format html|json, --directory-listing-download targz.

Checklist

• Do all files have correct extensions for MIME type detection?
• Are pre-compressed variants (.br/.gz/.zst) generated at build time?
• Are versioned assets using fingerprint filenames for cache busting?
• Is Cache-Control appropriate for the content type?
• Is the HTML entry point not cached (or has short TTL)?
• Are security headers enabled for production?
• Is TLS enabled for production deployments?