Configuration

This page documents the settings you can use to configure your server, and the default values that apply when you leave a setting unspecified. For the limits that apply to every server, refer to Limits.

Configuration sources

You can configure a server in two places:

In your entry file, by exporting a config object, or placing it inside the config property of a default export that's a Fetchable. This works whatever else your entry file exports, including a self-started server that exports nothing else.
In netlify.toml, in a [server] section.

Entry file
netlify.toml

import type { Config } from "@netlify/server";

export default async () => new Response("Hello, world");

export const config: Config = {
  region: "fra",
  size: "medium",
};

[server]
  region = "fra"
  size = "medium"

Both accept the same settings. If both set the same setting, the entry file takes precedence, one setting at a time.

The build fails if the configuration contains a setting that isn't listed on this page, or a value that isn't valid.

Routing

By default, your server receives every request that nothing else on your project handles. Requests go through the following steps, in order:

Edge Functions run first, and can rewrite requests or respond directly.
Redirect and rewrite rules are applied.
Static files from your deploy are served from the CDN.
Functions handle the paths they're configured for.
Everything else reaches your server, which owns its own routing, including its 404 responses.

Because static files are served before the request reaches your server, files in your publish directory never consume your server's compute. Prefer them for anything that is requested often.

Rewrite rules apply before your server too. A rule that matches every path, such as the /* /index.html 200 rule that single-page apps often use, sends requests to its destination instead of your server. Limit rules like this to the paths your frontend handles.

If your project uses a full-stack framework, its adapter usually creates a function for every path, so requests never reach your server. Refer to Full-stack frameworks.

Paths

path sets one or more URL paths that the server handles. Paths must begin with a forward slash, and use the same syntax as function paths.

Defaults to /*, which is every path that nothing else on your project handles. Static files always take precedence over the server, even on paths it claims, and paths under /.netlify/server/ are reserved for Netlify.

import type { Config } from "@netlify/server";

export default async () => new Response("Hello, world");

export const config: Config = {
  path: "/api/*",
};

Excluded paths

excludedPath sets one or more URL paths that the server doesn't handle, using the same syntax as path. Requests for them go on to the rest of your project as if the server didn't exist.

It works whether or not you set path. On its own, it leaves paths out of the default, which is every path that nothing else on your project handles.

import type { Config } from "@netlify/server";

export default async () => new Response("Hello, world");

export const config: Config = {
  excludedPath: ["/legacy/*", "/status"],
};

Caching

Responses from your server work with Netlify's edge cache, just like responses from functions. When a response is cached, later requests for it are served from the CDN and never reach your server, which makes them faster and saves your server's compute.

Responses aren't cached unless your server specifies it by setting caching headers. For example, to cache a response on the CDN for an hour, without the browser caching it:

export default async (req: Request) => {
  return Response.json(await getProducts(), {
    headers: { "Netlify-CDN-Cache-Control": "public, max-age=3600, durable" },
  });
};

app.get("/api/products", async (req, res) => {
  res.set("Netlify-CDN-Cache-Control", "public, max-age=3600, durable");
  res.json(await getProducts());
});

app.get("/api/products", async (c) => {
  c.header("Netlify-CDN-Cache-Control", "public, max-age=3600, durable");

  return c.json(await getProducts());
});

app.get("/api/products", async (request, reply) => {
  reply.header("Netlify-CDN-Cache-Control", "public, max-age=3600, durable");

  return getProducts();
});

All of the edge cache's features are available, including:

Cache control headers, including stale-while-revalidate and the durable directive, which shares a cached response across the CDN.
Cache key variation, to cache separate versions of a response by query parameter, header, language, country, or cookie.
On-demand invalidation, to purge cached responses by site or by cache tag.

Each deploy invalidates the responses cached from the previous one, so a new version of your server never serves responses that an older version generated.

Region

region sets the airport code of the region the server runs in. Defaults to cmh. Servers support the following regions:

Airport code	Region
`cmh`	US East (Ohio)
`fra`	EU (Frankfurt)

Instance size

size sets the size of the instances the server runs on. Defaults to small.

Size	Memory	vCPUs	Disk
`small`	1 GB	1, shared	512 MB
`medium`	2 GB	1	1 GB
`large`	4 GB	2	2 GB

On small instances, the vCPU is shared. When the machine your server runs on is busy, a small instance gets less CPU time than larger ones, so CPU-heavy work can take longer. If your server needs steady CPU performance, use medium or large.

Your server can write to the disk at /tmp, which is also what os.tmpdir() returns. The disk belongs to the instance and is emptied when the instance stops, so use it for temporary files only. The rest of the filesystem, including your code, is read-only.

Scale

scale sets how many instances your server runs. Netlify starts and stops instances as traffic changes, within these bounds:

min is the number of instances that keep running at all times, regardless of traffic. Defaults to 0, so your server scales to zero when nothing is using it.
max is the most instances that run at once. Defaults to the highest your plan allows.

Entry file
netlify.toml

import type { Config } from "@netlify/server";

export default async () => new Response("Hello, world");

export const config: Config = {
  scale: { max: 2 },
};

[server.scale]
  max = 2

Included files

includedFiles sets an array of glob patterns for additional files to include in the server's bundle, such as data files your server reads at runtime.

In the entry file, patterns are relative to the entry file. In netlify.toml, they're relative to your project's base directory, the same as a function's included_files. If both set includedFiles, the patterns in the entry file replace the ones in netlify.toml.

The files keep their place relative to your code. Your code can't rely on the working directory being the same everywhere, so resolve them relative to the module that reads them:

import type { Config } from "@netlify/server";
import { readFile } from "node:fs/promises";
import { join } from "node:path";

const seed = JSON.parse(await readFile(join(import.meta.dirname, "data", "seed.json"), "utf8"));

export default async () => Response.json(seed);

export const config: Config = {
  includedFiles: ["data/**"],
};

Environment variables

Your server reads environment variables through process.env. It receives the variables whose scopes include Functions, along with PORT, which Netlify sets to the port your server should listen on.

Their values are fixed when you deploy, so redeploy after changing a variable for your server to receive the new value.

Node.js version

Your server runs on the same major version of Node.js as your build, which you can set as described in Node.js and JavaScript. Netlify Server requires Node.js 24 or later, and the deploy fails if your build uses an earlier version.

Did you find this doc useful?

Your feedback helps us improve our docs.