Static files server

This guide covers serving static files in AdonisJS applications. You will learn how to:

• Install and configure the static files middleware
• Understand when to use static files versus compiled assets
• Configure caching, ETags, and HTTP headers for optimal performance
• Control access to dot files for security
• Set up custom headers for specific file types
• Copy static files to production builds

Overview

The static file server lets you serve files directly from the file system without creating route handlers for each file. This is essential for assets that don't need processing, like favicons, robots.txt files, user uploads, or downloadable PDFs.

Without a static file server, you would need to create individual routes for every file you want to serve. This quickly becomes unmaintainable:

// Without static middleware - tedious and error-prone
router.get('/favicon.ico', async ({ response }) => {
  return response.download('public/favicon.ico')
})
router.get('/robots.txt', async ({ response }) => {
  return response.download('public/robots.txt')
})
router.get('/images/logo.png', async ({ response }) => {
  return response.download('public/images/logo.png')
})
// ... potentially hundreds of routes

With the static middleware, all files in the public directory are automatically available. The middleware intercepts HTTP requests before they reach your routes. If a file matching the request path exists, it serves the file with appropriate HTTP headers for caching and performance. If no file exists, the request continues to your route handlers as normal.

The key distinction in AdonisJS: files in the public directory are served as-is without any processing, while files in the resources directory are processed by your assets bundler (like Vite). Use public for files that are already in their final form.

Installation

The @adonisjs/static package comes pre-configured with the web starter kit. If you're using a different starter kit, you can install and configure it manually.

Install and configure the package using the following command:

node ace add @adonisjs/static

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

    server.use([
      () => import('@adonisjs/static/static_middleware')
    ])

Configuration

The configuration for the static middleware is stored in 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: true
}

{
  etag: true
}

{
  lastModified: true
}

{
  dotFiles: 'ignore' // Recommended
}

{
  acceptRanges: true
}

{
  cacheControl: true
}

{
  cacheControl: true,
  maxAge: '30 days'
}

{
  cacheControl: true,
  maxAge: '1 year',
  immutable: true
}

{
  headers: (path, stats) => {
    /**
     * Set custom content type for .mc2 files
     * since they're not recognized by default
     */
    if (path.endsWith('.mc2')) {
      return {
        'content-type': 'application/octet-stream'
      }
    }

    /**
     * Add security headers for HTML files
     * to prevent XSS attacks
     */
    if (path.endsWith('.html')) {
      return {
        'X-Content-Type-Options': 'nosniff',
        'X-Frame-Options': 'DENY'
      }
    }
  }
}

Serving static files

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

Here's what a typical public directory looks like in production:

public/
├── favicon.ico           # Browser tab icon
├── robots.txt           # Search engine crawling instructions
├── sitemap.xml          # SEO sitemap for search engines
├── images/
│   ├── logo.png         # Static logo (doesn't need optimization)
│   └── og-image.jpg     # Social media preview image
├── downloads/
│   ├── user-guide.pdf   # Downloadable documentation
│   └── terms.pdf        # Legal documents
└── uploads/
    └── avatars/         # User-uploaded profile pictures

Each of these files would be accessible at its corresponding URL:

• http://localhost:3333/favicon.ico
• http://localhost:3333/images/logo.png
• http://localhost:3333/downloads/user-guide.pdf

public directory vs resources directory

Understanding when to use the public directory versus the resources directory is crucial for organizing your application's assets correctly.

Use the public directory for files that are already in their final form and don't need any processing:

• Favicons and app icons
• robots.txt and sitemap.xml files
• Static images that don't need optimization (logos, icons)
• Downloadable files (PDFs, ZIP archives, executables)
• Third-party JavaScript libraries you want to serve as-is
• User-uploaded content (avatars, documents)

Use the resources directory with an assets bundler for files that need compilation or optimization:

• CSS/SCSS files that need compilation
• Modern JavaScript/TypeScript that needs transpilation
• Images that benefit from optimization and responsive variants
• Assets that need versioning or cache-busting hashes
• Any file that should be processed by Vite or your build pipeline

public/styles/main.scss  # This won't be compiled
public/app.ts            # This won't be transpiled

resources/css/main.scss  # Compiled by Vite
resources/js/app.ts      # Transpiled by Vite

Copying static files to production

The files in your public directory are automatically copied to the build folder when you run the node ace build command. This ensures your static files are available in production alongside your compiled application code.

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

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

The pattern property uses glob syntax to match all files inside the public directory. The reloadServer: false setting indicates that changes to these files during development don't require restarting the development server.

If you add files to the public directory while your development server is running, you don't need to restart. The static middleware will serve them immediately. However, if you modify the config/static.ts file, you will need to restart the server for the configuration changes to take effect.

See also

• Middleware guide - Learn more about how middleware works in AdonisJS
• Vite integration - Set up asset compilation for the resources directory
• File uploads guide - Handle user-uploaded files that go in the public directory