fastify-static
Advanced tools
Plugin for serving static files as fast as possible. Supports Fastify version 3.x.
Please refer to this branch and related versions for Fastify ^2.0.0 compatibility.
Please refer to this branch and related versions for Fastify ^1.11.0 compatibility.
npm install --save fastify-static
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
})
fastify.get('/path/with/different/root', function (req, reply) {
reply.sendFile('myHtml.html', path.join(__dirname, 'build')) // serving a file from a different root location
})
const fastify = require('fastify')()
const fastifyStatic = require('fastify-static')
const path = require('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
})
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.
prefixDefault: '/'
A URL path prefix used to create a virtual mount path for the static directory.
prefixAvoidTrailingSlashDefault: false
If set to false prefix will get trailing "/" at the end. If set to true, prefix will not append "/" to prefix.
schemaHideDefault: true
A flag that define if the fastify route hide-schema attribute is hidden or not
setHeadersDefault: 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 OptionsThe following options are also supported and will be passed directly to the
send module:
redirectDefault: false
If set to true, fastify-static redirects to the directory with a trailing slash.
This option cannot be set to true with wildcard set to false on a server
with ignoreTrailingSlash set to true.
If this option is set to false, then requesting directories without trailing
slash will trigger your app's 404 handler using reply.callNotFound().
wildcardDefault: true
If set to true, fastify-static adds a wildcard route to serve files.
If set to false, fastify-static globs the filesystem for all defined
files in the served folder (${root}/**/*), and just creates the routes needed for
those.
If set to a glob string pattern, fastify-static will use the provided string when globing the filesystem (${root}/${wildcard}).
The default options of https://www.npmjs.com/package/glob are applied for getting the file list.
This option cannot be set to false with redirect set to true on a server
with ignoreTrailingSlash set to true.
listDefault: undefined
If set, it provide the directory list calling the directory path.
Default response is json.
Example:
fastify.register(require('fastify-static'), {
root: path.join(__dirname, 'public'),
prefix: '/public/',
list: true
})
Request
GET .../public
Response
{ "dirs": ["dir1", "dir2"], "files": ["file1.png", "file2.txt"] }
list.formatDefault: json
Options: html, json
Directory list can be also in html format; in that case, list.render function is required.
Example:
fastify.register(require('fastify-static'), {
root: path.join(__dirname, 'public'),
prefix: '/public/',
list: {
format: 'html',
render: (dirs, files) => {
return `
<html><body>
<ul>
${dirs.map(dir => `<li><a href="${dir.href}">${dir.name}</a></li>`).join('\n ')}
</ul>
<ul>
${files.map(file => `<li><a href="${file.href}" target="_blank">${file.name}</a></li>`).join('\n ')}
</ul>
</body></html>
`
},
}
})
Request
GET .../public
Response
<html><body>
<ul>
<li><a href="/dir1">dir1</a></li>
<li><a href="/dir1">dir2</a></li>
</ul>
<ul>
<li><a href="/foo.html" target="_blank">foo.html</a></li>
<li><a href="/foobar.html" target="_blank">foobar.html</a></li>
<li><a href="/index.css" target="_blank">index.css</a></li>
<li><a href="/index.html" target="_blank">index.html</a></li>
</ul>
</body></html>
list.namesDefault: ['']
Directory list can respond to different routes, declared in list.names options.
Note: if a file with the same name exists, the actual file is sent.
Example:
fastify.register(require('fastify-static'), {
root: path.join(__dirname, '/static'),
prefix: '/public',
prefixAvoidTrailingSlash: true,
list: {
format: 'json',
names: ['index', 'index.json', '/']
}
})
Dir list respond with the same content to
GET .../public
GET .../public/
GET .../public/index
GET .../public/index.json
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.
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.
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().
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().
stream.filenameIf 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()
})
Licensed under MIT
FAQs
`fastify-static@4.7.0` has been deprecated. Please use `@fastify/static@5.0.0` instead.
We found that fastify-static demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 17 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.