Skip to main content
Version: v4

Static Files

  • Added in: v4.5.0
  • Changed in: v4.7.0 - (Migrated to Plugin API and new options added)

The static built-in plugin serves static files from your Harper application over HTTP. Use it to host websites, SPAs, downloadable assets, or any static content alongside your Harper data and API endpoints.

static does not need to be installed — it is built into Harper and only needs to be declared in your config.yaml.

Basic Usage​

Configure static with the files option pointing to the files you want to serve:

static:
  files: 'site/**'

Given a component with this structure:

my-app/
├─ site/
│  ├─ index.html
│  ├─ about.html
│  ├─ blog/
│     ├─ post-1.html
│     ├─ post-2.html
├─ config.yaml

Files are accessed relative to the matched directory root, so GET /index.html returns site/index.html and GET /blog/post-1.html returns site/blog/post-1.html.

files and urlPath Options​

Added in: v4.5

static is a Plugin and supports the standard files and urlPath configuration options for controlling which files to serve and at what URL path.

Use urlPath to mount the files at a specific URL prefix:

static:
  files: 'site/**'
  urlPath: 'app'

Now GET /app/index.html returns site/index.html and GET /app/blog/post-1.html returns site/blog/post-1.html.

See Components Overview for full files glob pattern and urlPath documentation.

Additional Options​

Added in: v4.7

In addition to the standard files, urlPath, and timeout options, static supports these configuration options:

  • index - boolean - optional - If true, automatically serves index.html when a request targets a directory. Defaults to false.

  • extensions - string[] - optional - File extensions to try when an exact path match is not found. For example, extensions: ['html'] means a request for /page-1 will also try /page-1.html.

  • fallthrough - boolean - optional - If true, passes the request to the next handler when the requested file is not found. Set to false when using notFound to customize 404 responses. Defaults to true.

  • notFound - string | { file: string; statusCode: number } - optional - A custom file (or file + status code) to return when a path is not found. Useful for serving a custom 404 page or for SPAs that use client-side routing.

Auto-Updates​

Added in: v4.7.0

Because static uses the Plugin API, it automatically responds to changes without requiring a Harper restart. Adding, removing, or modifying files — or updating config.yaml — takes effect immediately.

Examples​

Basic static file serving​

Serve all files in the static/ directory. Requests must match file names exactly.

static:
  files: 'static/**'

Automatic index.html serving​

Serve index.html automatically when a request targets a directory:

static:
  files: 'static/**'
  index: true

With this structure:

my-app/
├─ static/
│  ├─ index.html
│  ├─ blog/
│     ├─ index.html
│     ├─ post-1.html

Request mappings:

GET /            -> static/index.html
GET /blog        -> static/blog/index.html
GET /blog/post-1.html -> static/blog/post-1.html

Automatic extension matching​

Combine index and extensions for clean URLs without file extensions:

static:
  files: 'static/**'
  index: true
  extensions: ['html']

Request mappings with the same structure:

GET /            -> static/index.html
GET /blog        -> static/blog/index.html
GET /blog/post-1 -> static/blog/post-1.html

Custom 404 page​

Return a specific file when a requested path is not found:

static:
  files: 'static/**'
  notFound: 'static/404.html'
  fallthrough: false

A request to /non-existent returns the contents of static/404.html with a 404 status code.

Note: When using notFound, set fallthrough: false so the request does not pass through to another handler before the custom 404 response is returned.

SPA client-side routing​

For SPAs that handle routing in the browser, return the main application file for any unmatched path:

static:
  files: 'static/**'
  fallthrough: false
  notFound:
    file: 'static/index.html'
    statusCode: 200

A request to any unmatched path returns static/index.html with a 200 status code, allowing the client-side router to handle navigation.