@fastify/static 8.1.1 → 8.2.0

package/.github/workflows/ci.yml

@@ -14,8 +14,14 @@ on:
       - 'docs/**'
       - '*.md'
 
+permissions:
+  contents: read
+
 jobs:
   test:
+    permissions:
+      contents: write
+      pull-requests: write
     uses: fastify/workflows/.github/workflows/plugins-ci.yml@v5
     with:
       license-check: true

package/README.md

@@ -15,10 +15,10 @@ npm i @fastify/static
 
 | Plugin version | Fastify version |
 | ---------------|-----------------|
-| `^8.x`         | `^5.x`          |
+| `>=8.x`        | `^5.x`          |
 | `^7.x`         | `^4.x`          |
-| `^5.x`         | `^3.x`          |
-| `^2.x`         | `^2.x`          |
+| `>=5.x <7.x`   | `^3.x`          |
+| `>=2.x <5.x`   | `^2.x`          |
 | `^1.x`         | `^1.x`          |
 
 
@@ -111,6 +111,31 @@ fastify.get('/path/without/cache/control', function (req, reply) {
 
 ```
 
+### Managing cache-control headers
+
+Production sites should use a reverse-proxy to manage caching headers.
+However, here is an example of using fastify-static to host a Single Page Application (for example a [vite.js](https://vite.dev/) build) with sane caching.
+
+```js
+fastify.register(require('@fastify/static'), {
+  root: path.join(import.meta.dirname, 'dist'), // import.meta.dirname node.js >= v20.11.0
+  // By default all assets are immutable and can be cached for a long period due to cache bursting techniques
+  maxAge: '30d',
+  immutable: true,
+})
+
+// Explicitly reduce caching of assets that don't use cache bursting techniques
+fastify.get('/', function (req, reply) {
+  // index.html should never be cached
+  reply.sendFile('index.html', {maxAge: 0, immutable: false})
+})
+
+fastify.get('/favicon.ico', function (req, reply) {
+  // favicon can be cached for a short period
+  reply.sendFile('favicon.ico', {maxAge: '1d', immutable: false})
+})
+```
+
 ### Options
 
 #### `root` (required)
@@ -208,6 +233,14 @@ are applied for getting the file list.
 
 This option cannot be `false` if `redirect` is `true` and `ignoreTrailingSlash` is `true`.
 
+#### `globIgnore`
+
+Default: `undefined`
+
+This is passed to [`glob`](https://www.npmjs.com/package/glob)
+as the `ignore` option. It can be used to ignore files or directories
+when using the `wildcard: false` option.
+
 #### `allowedPath`
 
 Default: `(pathName, root, request) => true`

package/index.js

@@ -135,7 +135,7 @@ async function fastifyStatic (fastify, opts) {
         rootPath = rootPath.split(path.win32.sep).join(path.posix.sep)
         !rootPath.endsWith('/') && (rootPath += '/')
         const files = await glob('**/**', {
-          cwd: rootPath, absolute: false, follow: true, nodir: true, dot: opts.serveDotFiles
+          cwd: rootPath, absolute: false, follow: true, nodir: true, dot: opts.serveDotFiles, ignore: opts.globIgnore
         })
 
         for (let file of files) {
@@ -284,6 +284,7 @@ async function fastifyStatic (fastify, opts) {
               prefix,
               dotfiles: opts.dotfiles
             }).catch((err) => reply.send(err))
+            return
           }
         }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastify/static",
-  "version": "8.1.1",
+  "version": "8.2.0",
   "description": "Plugin for serving static files as fast as possible.",
   "main": "index.js",
   "type": "commonjs",
@@ -59,7 +59,7 @@
   ],
   "dependencies": {
     "@fastify/accept-negotiator": "^2.0.0",
-    "@fastify/send": "^3.2.0",
+    "@fastify/send": "^4.0.0",
     "content-disposition": "^0.5.4",
     "fastify-plugin": "^5.0.0",
     "fastq": "^1.17.1",
@@ -69,7 +69,7 @@
     "@fastify/compress": "^8.0.0",
     "@fastify/pre-commit": "^2.1.0",
     "@types/node": "^22.0.0",
-    "borp": "^0.19.0",
+    "borp": "^0.20.0",
     "c8": "^10.1.3",
     "concat-stream": "^2.0.0",
     "eslint": "^9.17.0",
@@ -77,7 +77,7 @@
     "neostandard": "^0.12.0",
     "pino": "^9.1.0",
     "proxyquire": "^2.1.3",
-    "tsd": "^0.31.0"
+    "tsd": "^0.32.0"
   },
   "tsd": {
     "directory": "test/types"

package/test/static-filtered/bar.private

@@ -0,0 +1 @@
+bar

package/test/static-filtered/deep/path/to/baz.html

@@ -0,0 +1,3 @@
+<html>
+  <body>baz</body>
+</html>

package/test/static-filtered/deep/path/to/baz.private

@@ -0,0 +1 @@
+baz

package/test/static-filtered/index.html

@@ -0,0 +1,3 @@
+<html>
+  <body>index2</body>
+</html>

package/test/static.test.js

@@ -3669,3 +3669,77 @@ test('register /static/ with custom log level', async t => {
     t.assert.deepStrictEqual(response2.status, 304)
   })
 })
+
+test('register with wildcard false and globIgnore', async t => {
+  t.plan(5)
+
+  const indexContent = fs
+    .readFileSync('./test/static-filtered/index.html')
+    .toString('utf8')
+
+  const deepContent = fs
+    .readFileSync('./test/static-filtered/deep/path/to/baz.html')
+    .toString('utf8')
+
+  const pluginOptions = {
+    root: path.join(__dirname, '/static-filtered'),
+    wildcard: false,
+    globIgnore: ['**/*.private']
+  }
+  const fastify = Fastify()
+  fastify.register(fastifyStatic, pluginOptions)
+
+  t.after(() => fastify.close())
+
+  await fastify.listen({ port: 0 })
+
+  fastify.server.unref()
+
+  await t.test('/index.html', async t => {
+    t.plan(3 + GENERIC_RESPONSE_CHECK_COUNT)
+
+    const response = await fetch('http://localhost:' + fastify.server.address().port + '/index.html')
+    t.assert.ok(response.ok)
+    t.assert.deepStrictEqual(response.status, 200)
+    t.assert.deepStrictEqual(await response.text(), indexContent)
+    genericResponseChecks(t, response)
+  })
+
+  await t.test('/bar.private', async t => {
+    t.plan(2)
+
+    const response = await fetch('http://localhost:' + fastify.server.address().port + '/bar.private')
+    t.assert.ok(!response.ok)
+    t.assert.deepStrictEqual(response.status, 404)
+    await response.text()
+  })
+
+  await t.test('/', async (t) => {
+    t.plan(3 + GENERIC_RESPONSE_CHECK_COUNT)
+
+    const response = await fetch('http://localhost:' + fastify.server.address().port)
+    t.assert.ok(response.ok)
+    t.assert.deepStrictEqual(response.status, 200)
+    t.assert.deepStrictEqual(await response.text(), indexContent)
+    genericResponseChecks(t, response)
+  })
+
+  await t.test('/deep/path/to/baz.html', async (t) => {
+    t.plan(3 + GENERIC_RESPONSE_CHECK_COUNT)
+
+    const response = await fetch('http://localhost:' + fastify.server.address().port + '/deep/path/to/baz.html')
+    t.assert.ok(response.ok)
+    t.assert.deepStrictEqual(response.status, 200)
+    t.assert.deepStrictEqual(await response.text(), deepContent)
+    genericResponseChecks(t, response)
+  })
+
+  await t.test('/deep/path/to/baz.private', async (t) => {
+    t.plan(2)
+
+    const response = await fetch('http://localhost:' + fastify.server.address().port + '/deep/path/to/baz.private')
+    t.assert.ok(!response.ok)
+    t.assert.deepStrictEqual(response.status, 404)
+    await response.text()
+  })
+})

package/types/index.d.ts

@@ -94,6 +94,7 @@ declare namespace fastifyStatic {
     setHeaders?: (res: SetHeadersResponse, path: string, stat: Stats) => void;
     redirect?: boolean;
     wildcard?: boolean;
+    globIgnore?: string[];
     list?: boolean | ListOptionsJsonFormat | ListOptionsHtmlFormat;
     allowedPath?: (pathName: string, root: string, request: FastifyRequest) => boolean;
     /**

package/types/index.test-d.ts

@@ -50,6 +50,7 @@ const options: FastifyStaticOptions = {
   schemaHide: true,
   serve: true,
   wildcard: true,
+  globIgnore: ['**/*.private'],
   list: false,
   setHeaders: (res, path, stat) => {
     expectType<string>(res.filename)