static-file-serving

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:

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:

Compression ratios (typical for text files):

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):

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?