Configuration

While serve works out-of-the-box with zero configuration, you can customize its behavior by creating a serve.json file in the root of the directory you are serving.

`serve.json`

serve automatically looks for a serve.json file to apply advanced settings like custom rewrites, redirects, headers, and more. This file uses the same configuration schema as Vercel Deployments.

Here is an example serve.json file demonstrating some of the available options:

{
  "public": "dist",
  "cleanUrls": true,
  "rewrites": [
    { "source": "/api/**", "destination": "/api/index.js" }
  ],
  "redirects": [
    { "source": "/old-page", "destination": "/new-page", "type": 301 }
  ],
  "headers": [
    {
      "source": "**/*.@(jpg|jpeg|gif|png)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=7200"
        }
      ]
    }
  ],
  "trailingSlash": false,
  "symlinks": true
}

Configuration Options

Based on serve-handler and types.ts, the following properties are supported in serve.json:

Property	Type	Description
`public`	`string`	The directory to serve files from. If not set, the root directory being served is used.
`cleanUrls`	`boolean` or `string[]`	If `true`, automatically remove `.html` extensions from URLs. Can also be an array of globs.
`rewrites`	`Array<Rewrite>`	A list of rewrite rules. A rewrite changes the serving path without changing the URL in the browser.
`redirects`	`Array<Redirect>`	A list of redirect rules. A redirect sends an HTTP redirect status code (e.g., 301 or 302) to the client.
`headers`	`Array<Header>`	A list of rules for adding custom HTTP response headers.
`directoryListing`	`boolean` or `string[]`	Enable or disable the directory listing view. Can be a boolean or an array of globs to apply it to.
`unlisted`	`string[]`	An array of file or directory globs to hide from the directory listing.
`trailingSlash`	`boolean`	If `true`, adds a trailing slash to URLs that don't have one. If `false`, removes it.
`renderSingle`	`boolean`	If `true`, serves `index.html` for all requests that don't match a file. Equivalent to the `--single` flag.
`symlinks`	`boolean`	If `true`, resolves symbolic links. Equivalent to the `--symlinks` flag.
`etag`	`boolean`	If `true` (default), enables ETag headers for caching.

Object Shapes

Rewrite: { "source": "/path/:id", "destination": "/details.html" }
Redirect: { "source": "/old", "destination": "/new", "type": 301 } (type can be 301, 302, 307, 308).
Header: { "source": "/static/**", "headers": [{ "key": "X-Custom", "value": "hello" }] }

Deprecated Configuration Files

The source/utilities/config.ts file indicates that serve can also read configuration from now.json and package.json for backward compatibility. However, this is deprecated.

In now.json, configuration should be under now.static.
In package.json, configuration should be under static.

A warning will be printed if you use these files. It is strongly recommended to use a dedicated serve.json file for all your configuration needs.