fastify-static

What is fastify-static?

The fastify-static package is a Fastify plugin that allows you to serve static files, such as HTML, CSS, JavaScript, images, and other assets, from a directory. It is designed to be highly performant and easy to use, leveraging Fastify's speed and low overhead.

What are fastify-static's main functionalities?

Serve Static Files

This feature allows you to serve static files from a specified directory. In this example, files from the 'public' directory are served with the URL prefix '/public/'.

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

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

fastify.listen(3000, err => {
  if (err) throw err;
  console.log('Server listening on http://localhost:3000');
});

Serve Single Page Applications (SPA)

This feature is useful for serving Single Page Applications (SPA). When a route is not found, it serves the 'index.html' file, allowing the client-side router to handle the navigation.

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

fastify.register(require('fastify-static'), {
  root: path.join(__dirname, 'public'),
  wildcard: false
});

fastify.setNotFoundHandler((request, reply) => {
  reply.sendFile('index.html');
});

fastify.listen(3000, err => {
  if (err) throw err;
  console.log('Server listening on http://localhost:3000');
});

Serve Files with Custom Headers

This feature allows you to set custom headers for the served files. In this example, a custom header 'X-Custom-Header' is added to all responses.

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

fastify.register(require('fastify-static'), {
  root: path.join(__dirname, 'public'),
  setHeaders: (res, path, stat) => {
    res.setHeader('X-Custom-Header', 'fastify-static');
  }
});

fastify.listen(3000, err => {
  if (err) throw err;
  console.log('Server listening on http://localhost:3000');
});

Other packages similar to fastify-static

serve-static

The serve-static package is a middleware for serving static files in Express applications. It is similar to fastify-static but is designed for use with the Express framework. It offers similar functionality, such as serving files from a directory and setting custom headers.

koa-static

The koa-static package is a middleware for serving static files in Koa applications. Like fastify-static, it allows you to serve files from a directory and supports features like setting custom headers. It is designed to work with the Koa framework.

README

fastify-static

Plugin for serving static files as fast as possible. Supports Fastify versions >=2.0.0.

Please refer to this branch and related versions for Fastify ^1.11.0 compatibility.

Install

npm install --save fastify-static

Usage

const fastify = require('fastify')()
const path = require('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
})

Options

root (required)

The absolute path of the directory that contains the files to serve. The file to serve will be determined by combining req.url with the provided root directory.

prefix

Default: '/'

A URL path prefix used to create a virtual mount path for the static directory.

schemaHide

Default: true

A flag that define if the fastify route hide-schema attribute is hidden or not

setHeaders

Default: undefined

A function to set custom headers on the response. Alterations to the headers must be done synchronously. The function is called as fn(res, path, stat), where the arguments are:

• res The response object.
• path The path of the file that is being sent.
• stat The stat object of the file that is being sent.

send Options

The following options are also supported and will be passed directly to the send module:

• acceptRanges
• cacheControl
• dotfiles
• etag
• extensions
• immutable
• index
• lastModified
• maxAge

Disable serving

If you'd just like to use the reply decorator and not serve whole directories automatically, you can simply pass the option { serve: false }. This will prevent the plugin from serving everything under root.

Disabling reply decorator

The reply object is decorated with a sendFile function by default. If you want to disable this, pass the option { decorateReply: false }. If fastify-static is registers to multiple prefixes in the same route only one can initialize reply decorators.

Handling 404s

If a request matches the URL prefix but a file cannot be found for the request, Fastify's 404 handler will be called. You can set a custom 404 handler with fastify.setNotFoundHandler().

Handling Errors

If an error occurs while trying to send a file, the error will be passed to Fastify's error handler. You can set a custom error handler with fastify.setErrorHandler().

Payload stream.filename

If you need to access the filename inside the onSend hook, you can use payload.filename.

fastify.addHook('onSend', function (req, reply, payload, next) {
  console.log(payload.filename)
  next()
})

License

Licensed under MIT