Static Files

Static Files

Serve static files from any filesystem using http.static. Static handlers mount directly on the server and can serve SPAs, assets, or user uploads from any path.

Configuration

- name: static
  kind: http.static
  meta:
    server: gateway
  path: /
  fs: app:public
  static_options:
    spa: true
    index: index.html
    cache: "public, max-age=3600"

Field	Type	Description
meta.server	Registry ID	Parent HTTP server
path	string	URL mount path (must start with /)
fs	Registry ID	Filesystem entry to serve from
static_options.spa	bool	SPA mode - serve index for unmatched paths
static_options.index	string	Index file (required when spa=true)
static_options.cache	string	Cache-Control header value
middleware	[]string	Middleware chain
options	map	Middleware options (dot notation)

Static handlers can be mounted to any path on the server. Multiple handlers can coexist—mount assets at /static and an SPA at /.

Filesystem Integration

Static files are served from filesystem entries. Any filesystem type works:

entries:
  # Local directory
  - name: public
    kind: fs.directory
    directory: ./public

  # Static handler
  - name: static
    kind: http.static
    meta:
      server: gateway
    path: /static
    fs: public

Request /static/css/style.css serves ./public/css/style.css.

To serve a subdirectory, point the fs reference at a filesystem entry rooted there—for example an fs.directory with directory: set to the subdirectory:

entries:
  - name: content
    kind: fs.directory
    directory: ./app/documentation/html

  - name: docs
    kind: http.static
    meta:
      server: gateway
    path: /docs
    fs: content

SPA Mode

Single Page Applications need all routes to serve the same index file for client-side routing:

- name: spa
  kind: http.static
  meta:
    server: gateway
  path: /
  fs: app:frontend
  static_options:
    spa: true
    index: index.html

Request	Response
/app.js	Serves app.js (file exists)
/users/123	Serves index.html (SPA fallback)
/api/data	Serves index.html (SPA fallback)

When spa: true, the index file is required. Existing files are served directly; all other paths return the index file.

Cache Control

Set appropriate caching for different asset types:

entries:
  - name: app_fs
    kind: fs.directory
    directory: ./dist

  # Versioned assets - cache forever
  - name: assets
    kind: http.static
    meta:
      server: gateway
    path: /assets
    fs: app_fs
    static_options:
      cache: "public, max-age=31536000, immutable"

  # HTML - short cache, must revalidate
  - name: app
    kind: http.static
    meta:
      server: gateway
    path: /
    fs: app_fs
    static_options:
      spa: true
      index: index.html
      cache: "public, max-age=0, must-revalidate"

Common cache patterns:

• Versioned assets: public, max-age=31536000, immutable
• HTML/index: public, max-age=0, must-revalidate
• User uploads: private, max-age=3600

Middleware

Apply middleware for compression, CORS, or other processing:

- name: static
  kind: http.static
  meta:
    server: gateway
  path: /
  fs: app:public
  middleware:
    - compress
    - cors
  options:
    compress.level: "best"
    cors.allow.origins: "*"

Middleware wraps the static handler in order—requests pass through each middleware before reaching the file server.

Path matching is prefix-based. A handler at / catches all unmatched requests. Use routers for API endpoints to avoid conflicts.

See Also

• Server - HTTP server configuration
• Routing - Routers and endpoints
• Filesystem - Filesystem module
• Middleware - Available middleware