@fastify/static

You can register the plugin multiple times to serve different directories under different URL prefixes. Note that if you register the plugin multiple times, you should set decorateReply: false on subsequent registrations to avoid errors, as the reply.sendFile decorator is added by the first registration.

const fastify = require('fastify')()
const fastifyStatic = require('@fastify/static')
const path = require('node:path')

// first plugin
fastify.register(fastifyStatic, {
  root: path.join(__dirname, 'public')
})

// second plugin
fastify.register(fastifyStatic, {
  root: path.join(__dirname, 'node_modules'),
  prefix: '/node_modules/',
  decorateReply: false // the reply decorator has been added by the first plugin registration
})

Register @fastify/static to serve files from a specific directory. By default, files are served from the root directory at the / prefix. You can use reply.sendFile(path) to serve specific files within your route handlers.

const fastify = require('fastify')({logger: true})
const path = require('node:path')

fastify.register(require('@fastify/static'), {
  root: path.join(__dirname, 'public'),
  prefix: '/public/', // optional: default '/'
})

fastify.get('/another/path', function (req, reply) {
  reply.sendFile('myHtml.html') // serving path.join(__dirname, 'public', 'myHtml.html') directly
})

fastify.listen({ port: 3000 }, (err, address) => {
  if (err) throw err
})

When using @fastify/static inside an encapsulated context (e.g., via fastify.register with a scope), you may need to set wildcard: false to ensure that index resolution and nested setNotFoundHandler calls work correctly for files within that scope.

const app = require('fastify')();

app.register((childContext, _, done) => {
    childContext.register(require('@fastify/static'), {
        root: path.join(__dirname, 'docs'),
        wildcard: false
    });
    childContext.setNotFoundHandler((_, reply) => {
        return reply.code(404).type('text/html').sendFile('404.html');
    });
    done();
}, { prefix: 'docs' });

To use this plugin for serving static files in your Fastify application, install it using npm:

npm i @fastify/static

You can manage caching behavior globally via plugin options or per-request via reply.sendFile or reply.download options. This is particularly useful for Single Page Applications (SPAs) where immutable assets (like hashed JS/CSS) can have long maxAge values, while index.html should have maxAge: 0 to prevent caching.

// Global configuration for immutable assets
fastify.register(require('@fastify/static'), {
  root: path.join(import.meta.dirname, 'dist'),
  maxAge: '30d',
  immutable: true,
})

// Per-request override for non-cacheable files
fastify.get('/', function (req, reply) {
  reply.sendFile('index.html', {maxAge: 0, immutable: false})
})

The list option allows you to serve a directory listing. You can specify the format (json or html) and a render function if using HTML. If using json, you can control the detail level via list.jsonFormat (names or extended).

fastify.register(require('@fastify/static'), {
  root: path.join(__dirname, '/static'),
  prefix: '/public',
  prefixAvoidTrailingSlash: true,
  list: {
    format: 'json',
    names: ['index', 'index.json', '/']
  }
})

To serve static files in your Fastify application, register the @fastify/static plugin. You must provide a root option, which can be a single absolute path string, an array of absolute path strings, or a file:// URL.

By default, the plugin serves files under the / prefix. You can customize this using the prefix option.

const fastify = require('fastify')()
const fastifyStatic = require('@fastify/static')

fastify.register(fastifyStatic, {
  root: path.join(__dirname, 'public'),
  prefix: '/static',
})

Use reply.download(path, filename) to send a file and set the Content-Disposition header with a custom filename. This is useful for forcing a download with a specific name.

fastify.get('/download', function (req, reply) {
  reply.download('myHtml.html', 'custom-filename.html')
})

Errors thrown by the plugin can be caught and identified using the errors object exported from @fastify/static.

const { errors } = require('@fastify/static')