Core

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.

3 min readUpdated DocumentationEdit this page
On this page7

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.

TypeScript
TS
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

OptionTypeDefaultDescription
rootstringrequiredDirectory to serve. Resolved to an absolute path once, at startup.
prefixstring''URL prefix to strip before looking up the file. Requests outside the prefix pass through.
indexstring'index.html'File served for a directory request
maxAgenumber86400Cache-Control: public, max-age=<seconds>
dotfilesbooleanfalseServe 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 GET or HEAD,
  • the path is outside prefix,
  • the file does not exist, or a directory has no index file,
  • the path is a dotfile and dotfiles is false,
  • 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:

TypeScript
TS
app.use(serveStatic({ root: './public' }))
app.get('/api/health', (_req, res) => res.success({ ok: true }))

Caching

Every response carries:

HeaderValue
ETagWeak ETag from file size and modification time, e.g. W/"1a2b-18c3f..."
Last-ModifiedFile modification time
Cache-Controlpublic, max-age=<maxAge>
Accept-Rangesbytes

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:

TypeScript
TS
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:

TypeScript
TS
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))

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY