@fastify/static

@fastify/static is the official Fastify plugin for serving static files directly from a Node.js Fastify server. It registers a wildcard route (or, optionally, pre-globbed explicit routes) under a configurable path prefix, decorates the Fastify reply with sendFile() and download() helpers, and streams file contents through @fastify/send, handling caching headers, ETags, range requests, and content-type negotiation along the way.

Beyond basic file serving, the plugin supports multiple static roots mounted under one prefix, brotli/gzip pre-compressed asset negotiation via @fastify/accept-negotiator, JSON or HTML directory listings with extended folder metadata, and fine-grained control over dotfiles, redirects, and per-file cache-control overrides — making it equally suited to serving a handful of assets or hosting an entire single-page-application build.

What You Get

• sendFile() / download() reply decorators - call reply.sendFile('name.html') or reply.download(...) from any route handler, not just the wildcard route.
• Pre-compressed asset support - automatically serves .br or .gz siblings of a file based on the request’s Accept-Encoding header.
• Directory listings - opt-in JSON or HTML directory index responses, with an extended mode reporting recursive size/file-count metadata per folder.
• Multi-root mounting - register the plugin multiple times with different root directories under the same or different prefixes, served first-found-first-served.
• Typed error codes - configuration mistakes throw distinguishable FST_STATIC_* errors built on @fastify/error rather than generic exceptions.

Common Use Cases

• Serving a built SPA - host a Vite/webpack production build directly from Fastify, with long-lived immutable caching for hashed assets and no caching for index.html.
• Authenticated file downloads - expose download endpoints via reply.download() with a custom filename and content-disposition header.
• Static documentation sites - serve a folder of prebuilt HTML/CSS/JS docs with custom 404 handling scoped to an encapsulated Fastify context.
• Compressed asset delivery - serve versioned, pre-compressed (brotli/gzip) assets behind a CDN or reverse proxy, using the cache-control and ETag headers the plugin sets.

Under The Hood

Architecture The plugin is a single fastify-plugin-wrapped async function (index.js) that, depending on options, registers either one wildcard GET/HEAD route (prefix + '*') or pre-globs the filesystem up front (via glob) and registers one explicit route per file. It decorates the Fastify reply with sendFile and download, both of which funnel through an internal pumpSendToReply helper that streams the response using @fastify/send. Directory listing is factored out into lib/dirList.js, which uses fastq to bound filesystem concurrency when computing recursive folder statistics, and custom error types live in lib/errors.js on top of @fastify/error. This keeps the plugin a thin, single-purpose extension of Fastify’s routing layer rather than a standalone framework — the kind of narrowly scoped, composable plugin pattern the Fastify ecosystem is built around.

Tech Stack Written in plain CommonJS JavaScript for Node.js, targeting current Fastify major versions (compatibility table in the README tracks plugin version against Fastify ^5.x/^4.x/etc). Core dependencies are all from the Fastify org itself — @fastify/send for file streaming, @fastify/accept-negotiator for content-encoding negotiation, @fastify/error for typed errors, and fastify-plugin for plugin registration semantics — plus glob for filesystem globbing, fastq for concurrency-limited async queues, and content-disposition for download headers. Type definitions are hand-written in types/index.d.ts and exercised with tstyche rather than generated.

Code Quality Testing uses borp (Node’s built-in test runner wrapper) with c8 coverage enforced at 100% lines via --check-coverage --lines 100, backed by an extensive test/static.test.js suite (nearly 5,000 lines) plus dedicated suites for directory listing and content-type handling, alongside fixture directories covering dotfiles, symlinks, pre-compressed variants, and path-encoding edge cases. Errors are raised as distinguishable typed error classes rather than generic Error instances or silent fallbacks. Linting runs through neostandard (ESLint-based) with a dedicated lint/lint:fix script, and CI runs on GitHub Actions. Overall this reads as a mature, thoroughly tested plugin with no notable quality gaps.

API Design The public surface is intentionally small: register the plugin with a root, optionally set a prefix, and either rely on the automatic wildcard route or call the added sendFile/download reply methods explicitly. Sensible defaults (serve everything under /, cache-control on, dotfiles disallowed) mean a working setup takes one fastify.register() call, while power users get fine-grained knobs — multi-root arrays, per-request header overrides, custom directory-list rendering, and route constraints — without those options getting in the way of the common case. The README documents every option with runnable examples, which keeps the learning curve low despite the surface area.