Static Files
Serve HTML, CSS, images, video and downloads from a folder with serveStatic(): MIME types, ETag and 304 caching, byte ranges and traversal protection.
serveStatic() from @axiljs/core serves files from a directory. It streams files, sets MIME types and cache validators, answers conditional requests with 304 Not Modified, supports byte ranges for audio and video seeking, and refuses paths that escape the root.
1import { Application, serveStatic } from '@axiljs/core'
2
3const app = new Application()
4
5app.use(serveStatic({ root: './public' }))
6app.use(serveStatic({ root: './uploads', prefix: '/uploads' }))
7
8await app.listen(3000)GET /logo.png serves ./public/logo.png; GET /uploads/a.pdf serves ./uploads/a.pdf.
Options
| Option | Type | Default | Description |
|---|---|---|---|
root | string | required | Directory to serve. Resolved to an absolute path once, at startup. |
prefix | string | '' | URL prefix to strip before looking up the file. Requests outside the prefix pass through. |
index | string | 'index.html' | File served for a directory request |
maxAge | number | 86400 | Cache-Control: public, max-age=<seconds> |
dotfiles | boolean | false | Serve paths with a segment starting with . (such as .env) |
Pass-through behaviour
serveStatic() never sends a 404 itself. It calls next() and lets later middleware and routes answer when:
- the method is not
GETorHEAD, - the path is outside
prefix, - the file does not exist, or a directory has no index file,
- the path is a dotfile and
dotfilesisfalse, - the decoded path would resolve outside
root(/../../etc/passwd), - the URL contains invalid percent-encoding.
So you can register it before your API routes and both work:
app.use(serveStatic({ root: './public' }))
app.get('/api/health', (_req, res) => res.success({ ok: true }))Caching
Every response carries:
| Header | Value |
|---|---|
ETag | Weak ETag from file size and modification time, e.g. W/"1a2b-18c3f..." |
Last-Modified | File modification time |
Cache-Control | public, max-age=<maxAge> |
Accept-Ranges | bytes |
A request with a matching If-None-Match, or an If-Modified-Since not older than the file, gets 304 Not Modified with no body. If-None-Match takes precedence, per RFC 9110.
For fingerprinted build assets (app.3f9a1c.js), raise maxAge:
app.use(serveStatic({ root: './dist/assets', prefix: '/assets', maxAge: 31536000 }))Range requests
A single Range: bytes=start-end is answered with 206 Partial Content and Content-Range, which lets browsers seek in <video> and <audio> and resume downloads. Suffix ranges (bytes=-500) work. A range past the end of the file gets 416 Range Not Satisfiable. Multi-range requests receive the whole file.
If-Range is honoured with a date validator; because the ETag is weak, an ETag in If-Range causes the full file to be sent.
MIME types
Common types are built in: html, css, js, json, xml, txt, md, png, jpg/jpeg, gif, svg, ico, webp, mp4, mp3, pdf, woff, woff2, ttf, eot. Other extensions are sent as application/octet-stream.
Single-page apps
serveStatic() serves files that exist. For client-side routing, add a catch-all route after it that returns index.html:
1import { readFileSync } from 'node:fs'
2
3const indexHtml = readFileSync('./public/index.html', 'utf8')
4
5app.use(serveStatic({ root: './public' }))
6app.get('/api/*', (_req, res) => res.notFound('No such endpoint'))
7app.get('/*', (_req, res) => res.html(indexHtml))Related
Was this page helpful?