stiff

An opinionated static file web server. Built to make serving static websites fast and easy.

Features

• Clean URLs - no trailing slashes or .html extensions
• Serve precompressed files (brotli and gzip) for faster downloads
• Easy resource caching via ETag and Last-Modified headers
• Set your own headers for even better caching and security

NOTE: stiff is meant to be used behind a reverse proxy, features like HTTPS, access logs, etc. are not provided.

Usage

• Place the files to be served in a directory named public
• While the server is running, these files must not be modified (including additions)
• For precompressed files, the filename must match the original with a .gz and .br extension
• To generate the precompressed files, you will have to use a separate tool like prepa

Configuration

By default, the server will listen on port 1717, but it can be set via the PORT environment variable.

You can configure stiff with a JSON file called stiff.json (at the root, not inside the public directory).

Error pages can be customized by providing 404.html and 500.html in the public directory.

Example stiff.json

{
    "headers": {
        "X-Content-Type-Options": "nosniff",
        "Cache-Control": "public, no-cache"
    },
    "lastmod": true,
    "routes": {
        "/": { "lastmod": false },
        "/app": { "serve": "webapp.html" },
        "/app/": { "serve": "webapp.html" },
        "/assets/": {
            "headers": { "Cache-Control": "public, max-age=300" }
        },
        "/assets/videos/": {
            "headers": { "Cache-Control": "public, max-age=300" },
            "etag": false
        }
    },
    "mimetypes": {
        ".atom":  "application/atom+xml"
    }
}

Top-Level Options

Key	Description
headers	Set additional headers
etag	Set the ETag header (default: true)
lastmod	Set the Last-Modified header (default: false)
mimetypes	Set custom MIME types; extensions must begin with a dot (.)

Route-Level Options

• Route-level options are placed under the routes key
• Routes must begin with a slash (/)
• Routes must end with a slash (/) for directories, i.e. /assets is separate from /assets/
• Only the most specific route match is applied (they don't cascade)

Key	Description
headers	Same as the top-level; headers will merge with the ones specified at the top-level
etag	Same as the top-level; if not specified, the top-level value will be used
lastmod	Same as the top-level; if not specified, the top-level value will be used
serve	Always serve the specified file for all subpaths (for SPAs)