Static files server

You can serve static files from a given directory using the @adonisjs/static package. The package ships with a middleware that you must register in the server middleware stack to intercept the HTTP requests and serve files.

Installation

The package comes pre-configured with the web starter kit. However, you can install it as follows with other starter kits.

npm i @adonisjs/static

yarn add @adonisjs/static

pnpm add @adonisjs/static

Once done, you must run the following command to configure the @adonisjs/static package.

node ace configure @adonisjs/static

Registers the following service provider inside the adonisrc.ts file.

{
  providers: [
    // ...other providers
    () => import('@adonisjs/static/static_provider')
  ]
}

Create the config/static.ts file.
Registers the following middleware inside the start/kernel.ts file.
```
server.use([
  () => import('@adonisjs/static/static_middleware')
])
```

Configuration

The configuration for the static middleware is stored inside the config/static.ts file.

import { defineConfig } from '@adonisjs/static'

const staticServerConfig = defineConfig({
  enabled: true,
  etag: true,
  lastModified: true,
  dotFiles: 'ignore',
})

export default staticServerConfig

enabled

Enable or disable the middleware temporarily without removing it from the middleware stack.

acceptRanges

The Accept-Range header allows browsers to resume an interrupted file download instead of trying to restart the download. You can disable resumable downloads by setting acceptsRanges to false.

Defaults to true.

cacheControl

Enable or disable the Cache-Control header. The immutable and maxAge properties will be ignored when cacheControl is disabled.

{
  cacheControl: true
}

dotFiles

Define how to treat requests for dot files inside the public directory. You can set one of the following options.

allow: Serve the dot-file same as the other files.
deny: Deny the request with the 403 status code.
ignore: Pretend the file does not exist and respond with a 404 status code.

{
  dotFiles: 'ignore'
}

etag

Enable or disable etag generation.

{
  etag: true,
}

lastModified

Enable or disable the Last-Modified header. The file stat.mtime property is used as the value for the header.

{
  lastModified: true,
}

immutable

Enable or disable the immutable directive for the Cache-Control header. By default, the immutable property is disabled.

If the immutable property is enabled, you must define the maxAge property to enable caching.

{
  immutable: true
}

maxAge

Define the max-age directive for the Cache-Control header. The value should be either in milliseconds or a time expression string.

{
  maxAge: '30 mins'
}

headers

A function that returns an object of headers to set on the response. The function receives the file path as the first argument and the file stats object as the second argument.

{
  headers: (path, stats) => {
    if (path.endsWith('.mc2')) {
      return {
        'content-type': 'application/octet-stream'
      }
    }
  }
}

Serving static files

Once the middleware is registered, you may create files inside the public directory and access them in the browser using the file path. For example, the ./public/css/style.css file can be accessed using the http://localhost:3333/css/style.css URL.

The files in the public directory are not compiled or built using an assets bundler. If you want to compile frontend assets, you must place them inside the resources directory and use the assets bundler.

Copying static files to production build

The static files stored inside the /public directory are automatically copied to the build folder when you run node ace build command.

The rule for copying public files is defined inside the adonisrc.ts file.

{
  metaFiles: [
    {
      pattern: 'public/**',
      reloadServer: false
    }
  ]
}

Static files server

Installation

Configuration

Serving static files

Copying static files to production build

On this page