How to serve static files with Fastify

Introduction #

Fastify does not allow static files to be returned as responses by default. To handle static files such as images and videos, you need to configure the fastify-static plugin and allow access to static files. In this post, we’ll take a closer look at routing static files and using virtual path prefixes.

Here, we will explain the routing method using the following versions.

Fastify v3.25.1
Node v20.7.0

In addition, all the code created this time is posted on GitHub.

Static file routing #

The minimal code to serve static files is below.

static.js

const fastify = require('fastify')({ logger: true })
const path = require('path')
const fastifyStatic = require('fastify-static')

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

fastify.listen(3000, (err, address) => {
  if (err) throw err
  fastify.log.info(`Server listening on ${address}`)
})

Commentary #

• Import Fastify and path modules

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

The above code loads the modules named fastify and path.

• register fastify-static plugin

const fastifyStatic = require('fastify-static')

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

The code above uses the fastify-static plugin to host static files in a directory named “public”. This allows files in this directory to be accessed directly with URLs that use the file name as the path.

• Start server

fastify.listen(3000, (err, address) => {
  if (err) throw err
  fastify.log.info(`Server listening on ${address}`)
})

This code will start the server on port 3000. If the server starts successfully, you will see the message ‘Server listening on ${address}’ on the console.

/public/static.txt

hello world

And set up the directory structure as follows:

/root
|-- static.js
|-- public
    |-- static.txt

With the above settings, you can access static files placed in the public folder.

curl http://localhost:3000/public/static.txt

Using virtual path prefix #

Exposing your project’s directory structure as-is can pose a security problem. To solve that problem, using a virtual path prefix is ​​recommended.

A virtual path prefix is ​​the ability to set a path that does not exist in the actual file system path and map it to a specific directory.

virtual.js

const fastify = require('fastify')({ logger: true })
const path = require('path')
const fastifyStatic = require('fastify-static')

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

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

fastify.listen(3000, (err, address) => {
  if (err) throw err
  fastify.log.info(`Server listening on ${address}`)
})

Commentary #

Importing modules and path modules

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

The above code loads the modules named fastify and path.

• register fastify-static plugin

const fastifyStatic = require('fastify-static')

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

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

This code first loads the fastify-static plugin and registers it with the Fastify server. And it hosts static files in two directories, public and virtual. Files in these directories can then be accessed directly with URLs that use the respective directory name and filename as the path.

• Start server

fastify.listen(3000, (err, address) => {
  if (err) throw err
  fastify.log.info(`Server listening on ${address}`)
})

This code will start the server on port 3000. If the server starts successfully, you will see the message ‘Server listening on ${address}’ on the console.

And set up the directory structure as follows:

/root
|-- virtual.js
|-- public
    |-- static.txt
|-- virtual
    |-- virtual.txt

With the above settings, you can access static files placed in the public folder and virtual folder.

curl http://localhost:3000/public/static.txt
curl http://localhost:3000/virtual/virtual.txt

So far, we’ve covered how to efficiently handle static files with Fastify and use virtual path prefixes. These methods allow for more secure and efficient static file handling.

summary #

For hosting static content Fastify provides the fastify-static plugin. This plugin makes it easy to write code for hosting static files. Also, using a virtual path prefix can solve security problems.