Skip to content

Latest commit

 

History

History
82 lines (62 loc) · 2.72 KB

README.md

File metadata and controls

82 lines (62 loc) · 2.72 KB

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)