express.static

express.static(root, [options])

This is a built-in middleware function in Express. It serves static files and is based on serve-static.

{% capture alert_content %} For best results, use a reverse proxy cache to improve performance of serving static assets. {% endcapture %} {% include admonitions/note.html content=alert_content %}

The root argument specifies the root directory from which to serve static assets. The function determines the file to serve by combining req.url with the provided root directory. When a file is not found, instead of sending a 404 response, it calls next() to move on to the next middleware, allowing for stacking and fall-backs.

The following table describes the properties of the options object. See also the example below.

Property	Description	Type	Default
`dotfiles`	Determines how dotfiles (files or directories that begin with a dot ”.”) are treated. See dotfiles below.	String	`undefined`
`etag`	Enable or disable etag generation NOTE: `express.static` always sends weak ETags.	Boolean	`true`
`extensions`	Sets file extension fallbacks: If a file is not found, search for files with the specified extensions and serve the first one found. Example: `['html', 'htm']`.	Mixed	`false`
`fallthrough`	Let client errors fall-through as unhandled requests, otherwise forward a client error. See fallthrough below.	Boolean	`true`
`immutable`	Enable or disable the `immutable` directive in the `Cache-Control` response header. If enabled, the `maxAge` option should also be specified to enable caching. The `immutable` directive will prevent supported clients from making conditional requests during the life of the `maxAge` option to check if the file has changed.	Boolean	`false`
`index`	Sends the specified directory index file. Set to `false` to disable directory indexing.	Mixed	”index.html”
`lastModified`	Set the `Last-Modified` header to the last modified date of the file on the OS.	Boolean	`true`
`maxAge`	Set the max-age property of the Cache-Control header in milliseconds or a string in ms format.	Number	0
`redirect`	Redirect to trailing ”/” when the pathname is a directory.	Boolean	`true`
`setHeaders`	Function for setting HTTP headers to serve with the file. See setHeaders below.	Function
`acceptRanges`	Enable or disable accepting ranged requests. Disabling this will not send the `Accept-Ranges` header and will ignore the contents of the Range request header.	Boolean	true
`cacheControl`	Enable or disable setting the `Cache-Control` response header. Disabling this will ignore the immutable and maxAge options.	Boolean	true

For more information, see Serving static files in Express. and Using middleware - Built-in middleware.

dotfiles

Possible values for this option are:

“allow” - No special treatment for dotfiles.
“deny” - Deny a request for a dotfile, respond with 403, then call next().
“ignore” - Act as if the dotfile does not exist, respond with 404, then call next().
undefined - Act as ignore, except that files in a directory that begins with a dot are NOT ignored.

fallthrough

When this option is true, client errors such as a bad request or a request to a non-existent file will cause this middleware to simply call next() to invoke the next middleware in the stack. When false, these errors (even 404s), will invoke next(err).

Set this option to true so you can map multiple physical directories to the same web address or for routes to fill in non-existent files.

Use false if you have mounted this middleware at a path designed to be strictly a single file system directory, which allows for short-circuiting 404s for less overhead. This middleware will also reply to all methods.

setHeaders

For this option, specify a function to set custom response headers. Alterations to the headers must occur synchronously.

The signature of the function is:

fn(res, path, stat);

Arguments:

res, the response object.
path, the file path that is being sent.
stat, the stat object of the file that is being sent.

Example of express.static

Here is an example of using the express.static middleware function with an elaborate options object:

var options = {
  dotfiles: 'ignore',
  etag: false,
  extensions: ['htm', 'html'],
  index: false,
  maxAge: '1d',
  redirect: false,
  setHeaders: function (res, path, stat) {
    res.set('x-timestamp', Date.now());
  },
};

app.use(express.static('public', options));