Build Output Configuration

.vercel/output/config.json

Schema (as TypeScript):

type Config = {
  version: 3;
  routes?: Route[];
  images?: ImagesConfig;
  wildcard?: WildcardConfig;
  overrides?: OverrideConfig;
  cache?: string[];
  crons?: CronsConfig;
};

Config Types:

Route
ImagesConfig
WildcardConfig
OverrideConfig
CronsConfig

The config.json file contains configuration information and metadata for a Deployment. The individual properties are described in greater detail in the sub-sections below.

At a minimum, a config.json file with a "version" property is required.

`config.json` supported properties

version

.vercel/output/config.json

The version property indicates which version of the Build Output API has been implemented. The version described in this document is version 3.

`version` example

  "version": 3

routes

.vercel/output/config.json

vercel/examples/build-output-api/routes

The routes property describes the routing rules that will be applied to the Deployment. It uses the same syntax as the routes property of the vercel.json file.

Routes may be used to point certain URL paths to others on your Deployment, attach response headers to paths, and various other routing-related use-cases.

type Route = Source | Handler;

`Source` route

type Source = {
  src: string;
  dest?: string;
  headers?: Record<string, string>;
  methods?: string[];
  continue?: boolean;
  caseSensitive?: boolean;
  check?: boolean;
  status?: number;
  has?: HasField;
  missing?: HasField;
  locale?: Locale;
  middlewareRawSrc?: string[];
  middlewarePath?: string;
  mitigate?: Mitigate;
  transforms?: Transform[];
};

Key	Type	Required	Description
src	String	Yes	A PCRE-compatible regular expression that matches each incoming pathname (excluding querystring).
dest	String	No	A destination pathname or full URL, including querystring, with the ability to embed capture groups as $1, $2, or named capture value $name.
headers	Map	No	A set of headers to apply for responses.
methods	String[]	No	A set of HTTP method types. If no method is provided, requests with any HTTP method will be a candidate for the route.
continue	Boolean	No	A boolean to change matching behavior. If true, routing will continue even when the src is matched.
caseSensitive	Boolean	No	Specifies whether or not the route `src` should match with case sensitivity.
check	Boolean	No	If `true`, the route triggers `handle: 'filesystem'` and `handle: 'rewrite'`
status	Number	No	A status code to respond with. Can be used in tandem with Location: header to implement redirects.
has	HasField	No	Conditions of the HTTP request that must exist to apply the route.
missing	HasField	No	Conditions of the HTTP request that must NOT exist to match the route.
locale	Locale	No	Conditions of the Locale of the requester that will redirect the browser to different routes.
middlewareRawSrc	String[]	No	A list containing the original routes used to generate the `middlewarePath`.
middlewarePath	String	No	Path to an Edge Runtime function that should be invoked as middleware.
mitigate	Mitigate	No	A mitigation action to apply to the route.
transforms	Transform[]	No	A list of transforms to apply to the route.

Source route: `MatchableValue`

type MatchableValue = {
  eq?: string | number;
  neq?: string;
  inc?: string[];
  ninc?: string[];
  pre?: string;
  suf?: string;
  re?: string;
  gt?: number;
  gte?: number;
  lt?: number;
  lte?: number;
};

Key	Type	Required	Description
eq	String \| Number	No	Value must equal this exact value.
neq	String	No	Value must not equal this value.
inc	String[]	No	Value must be included in this array.
ninc	String[]	No	Value must not be included in this array.
pre	String	No	Value must start with this prefix.
suf	String	No	Value must end with this suffix.
re	String	No	Value must match this regular expression.
gt	Number	No	Value must be greater than this number.
gte	Number	No	Value must be greater than or equal to this number.
lt	Number	No	Value must be less than this number.
lte	Number	No	Value must be less than or equal to this number.

Source route: `HasField`

type HasField = Array<
  | { type: 'host'; value: string | MatchableValue }
  | {
      type: 'header' | 'cookie' | 'query';
      key: string;
      value?: string | MatchableValue;
    }
>;

Key	Type	Required	Description
type	"host" \| "header" \| "cookie" \| "query"	Yes	Determines the HasField type.
key	String	No*	Required for header, cookie, and query types. The key to match against.
value	String \| MatchableValue	No	The value to match against using string or MatchableValue conditions.

Source route: `Locale`

type Locale = {
  redirect?: Record<string, string>;
  cookie?: string;
};

Key	Type	Required	Description
redirect	Map	Yes	An object of keys that represent locales to check for (`en`, `fr`, etc.) that map to routes to redirect to (`/`, `/fr`, etc.).
cookie	String	No	Cookie name that can override the Accept-Language header for determining the current locale.

Source route: `Mitigate`

type Mitigate = {
  action: 'challenge' | 'deny';
};

Key	Type	Required	Description
action	"challenge" \| "deny"	Yes	The action to take when the route is matched.

Source route: `Transform`

type Transform = {
  type: 'request.headers' | 'request.query' | 'response.headers';
  op: 'append' | 'set' | 'delete';
  target: {
    key: string | Omit<MatchableValue, 're'>; // re is not supported for transforms
  };
  args?: string | string[];
};

Key	Type	Required	Description
type	"request.headers" \| "response.headers" \| "request.query"	Yes	The type of transform to apply.
op	"append" \| "set" \| "delete"	Yes	The operation to perform on the target.
target	`{ key: string \| Omit<MatchableValue, 're'> }`	Yes	The target of the transform. Regular expression matching is not supported.
args	String \| String[]	No	The arguments to pass to the transform.

Handler route

The routing system has multiple phases. The handle value indicates the start of a phase. All following routes are only checked in that phase.

type HandleValue =
  | 'rewrite'
  | 'filesystem' // check matches after the filesystem misses
  | 'resource'
  | 'miss' // check matches after every filesystem miss
  | 'hit'
  | 'error'; //  check matches after error (500, 404, etc.)
 
type Handler = {
  handle: HandleValue;
  src?: string;
  dest?: string;
  status?: number;
};

Key	Type	Required	Description
handle	HandleValue	Yes	The phase of routing when all subsequent routes should apply.
src	String	No	A PCRE-compatible regular expression that matches each incoming pathname (excluding querystring).
dest	String	No	A destination pathname or full URL, including querystring, with the ability to embed capture groups as $1, $2.
status	String	No	A status code to respond with. Can be used in tandem with `Location:` header to implement redirects.

Routing rule example

The following example shows a routing rule that will cause the /redirect path to perform an HTTP redirect to an external URL:

  "routes": [
    {
      "src": "/redirect",
      "status": 308,
      "headers": { "Location": "https://example.com/" }
    }
  ]

images

.vercel/output/config.json

vercel/examples/build-output-api/image-optimization

The images property defines the behavior of Vercel's native Image Optimization API, which allows on-demand optimization of images at runtime.

type ImageFormat = 'image/avif' | 'image/webp';
 
type RemotePattern = {
  protocol?: 'http' | 'https';
  hostname: string;
  port?: string;
  pathname?: string;
  search?: string;
};
 
type LocalPattern = {
  pathname?: string;
  search?: string;
};
 
type ImagesConfig = {
  sizes: number[];
  domains: string[];
  remotePatterns?: RemotePattern[];
  localPatterns?: LocalPattern[];
  qualities?: number[];
  minimumCacheTTL?: number; // seconds
  formats?: ImageFormat[];
  dangerouslyAllowSVG?: boolean;
  contentSecurityPolicy?: string;
  contentDispositionType?: string;
};

Key	Type	Required	Description
sizes	Number[]	Yes	Allowed image widths.
domains	String[]	Yes	Allowed external domains that can use Image Optimization. Leave empty for only allowing the deployment domain to use Image Optimization.
remotePatterns	RemotePattern[]	No	Allowed external patterns that can use Image Optimization. Similar to `domains` but provides more control with RegExp.
localPatterns	LocalPattern[]	No	Allowed local patterns that can use Image Optimization. Leave undefined to allow all or use empty array to deny all.
qualities	Number[]	No	Allowed image qualities. Leave undefined to allow all possibilities, 1 to 100.
minimumCacheTTL	Number	No	Cache duration (in seconds) for the optimized images.
formats	ImageFormat[]	No	Supported output image formats
dangerouslyAllowSVG	Boolean	No	Allow SVG input image URLs. This is disabled by default for security purposes.
contentSecurityPolicy	String	No	Change the Content Security Policy of the optimized images.
contentDispositionType	String	No	Specifies the value of the `"Content-Disposition"` response header.

`images` example

The following example shows an image optimization configuration that specifies allowed image size dimensions, external domains, caching lifetime and file formats:

  "images": {
    "sizes": [640, 750, 828, 1080, 1200],
    "domains": [],
    "minimumCacheTTL": 60,
    "formats": ["image/avif", "image/webp"],
    "qualities": [25, 50, 75],
    "localPatterns": [{
      "pathname": "^/assets/.*$",
      "search": ""
    }]
    "remotePatterns": [{
      "protocol": "https",
      "hostname": "^via\\.placeholder\\.com$",
      "port": "",
      "pathname": "^/1280x640/.*$",
      "search": "?v=1"
    }]
  }

When the images property is defined, the Image Optimization API will be available by visiting the /_vercel/image path. When the images property is undefined, visiting the /_vercel/image path will respond with 404 Not Found.

The API accepts the following query string parameters:

Key	Type	Required	Example	Description
url	String	Yes	`/assets/me.png`	The URL of the source image that should be optimized. Absolute URLs must match a pattern defined in the `remotePatterns` configuration.
w	Integer	Yes	`200`	The width (in pixels) that the source image should be resized to. Must match a value defined in the `sizes` configuration.
q	Integer	Yes	`75`	The quality that the source image should be reduced to. Must be between 1 (lowest quality) to 100 (highest quality).

wildcard

.vercel/output/config.json

vercel/examples/build-output-api/wildcard

The wildcard property relates to Vercel's Internationalization feature. The way it works is the domain names listed in this array are mapped to the $wildcard routing variable, which can be referenced by the routes configuration.

Each of the domain names specified in the wildcard configuration will need to be assigned as Production Domains in the Project Settings.

type WildCard = {
  domain: string;
  value: string;
};
 
type WildcardConfig = Array<WildCard>;

`wildcard` supported properties

Objects contained within the wildcard configuration support the following properties:

Key	Type	Required	Description
domain	String	Yes	The domain name to match for this wildcard configuration.
value	String	Yes	The value of the `$wildcard` match that will be available for `routes` to utilize.

`wildcard` example

The following example shows a wildcard configuration where the matching domain name will be served the localized version of the blog post HTML file:

  "wildcard": [
    {
      "domain": "example.com",
      "value": "en-US"
    },
    {
      "domain": "example.nl",
      "value": "nl-NL"
    },
    {
      "domain": "example.fr",
      "value": "fr"
    }
  ],
  "routes": [
    { "src": "/blog", "dest": "/blog.$wildcard.html" }
  ]

overrides

.vercel/output/config.json

vercel/examples/build-output-api/overrides

The overrides property allows for overriding the output of one or more static files contained within the .vercel/output/static directory.

The main use-cases are to override the Content-Type header that will be served for a static file, and/or to serve a static file in the Vercel Deployment from a different URL path than how it is stored on the file system.

type Override = {
  path?: string;
  contentType?: string;
};
 
type OverrideConfig = Record<string, Override>;

`overrides` supported properties

Objects contained within the overrides configuration support the following properties:

Key	Type	Required	Description
path	String	No	The URL path where the static file will be accessible from.
contentType	String	No	The value of the `Content-Type` HTTP response header that will be served with the static file.

`overrides` example

The following example shows an override configuration where an HTML file can be accessed without the .html file extension:

  "overrides": {
    "blog.html": {
      "path": "blog"
    }
  }

cache

.vercel/output/config.json

The cache property is an array of file paths and/or glob patterns that should be re-populated within the build sandbox upon subsequent Deployments.

Note that this property is only relevant when Vercel is building a Project from source code, meaning it is not relevant when building locally or when creating a Deployment from "prebuilt" build artifacts.

type Cache = string[];

`cache` example

  "cache": [
    ".cache/**",
    "node_modules/**"
  ]

framework

.vercel/output/config.json

The optional framework property is an object describing the framework of the built outputs.

This value is used for display purposes only.

type Framework = {
  version: string;
};

`framework` example

  "framework": {
    "version": "1.2.3"
  }

crons

.vercel/output/config.json

The optional crons property is an object describing the cron jobs for the production deployment of a project.

type Cron = {
  path: string;
  schedule: string;
};
 
type CronsConfig = Cron[];

`crons` example

  "crons": [{
    "path": "/api/cron",
    "schedule": "0 0 * * *"
  }]

Full `config.json` example

{
  "version": 3,
  "routes": [
    {
      "src": "/redirect",
      "status": 308,
      "headers": { "Location": "https://example.com/" }
    },
    {
      "src": "/blog",
      "dest": "/blog.$wildcard.html"
    }
  ],
  "images": {
    "sizes": [640, 750, 828, 1080, 1200],
    "domains": [],
    "minimumCacheTTL": 60,
    "formats": ["image/avif", "image/webp"],
    "qualities": [25, 50, 75],
    "localPatterns": [{
      "pathname": "^/assets/.*$",
      "search": ""
    }]
    "remotePatterns": [
      {
        "protocol": "https",
        "hostname": "^via\\.placeholder\\.com$",
        "port": "",
        "pathname": "^/1280x640/.*$",
        "search": "?v=1"
      }
    ]
  },
  "wildcard": [
    {
      "domain": "example.com",
      "value": "en-US"
    },
    {
      "domain": "example.nl",
      "value": "nl-NL"
    },
    {
      "domain": "example.fr",
      "value": "fr"
    }
  ],
  "overrides": {
    "blog.html": {
      "path": "blog"
    }
  },
  "cache": [".cache/**", "node_modules/**"],
  "framework": {
    "version": "1.2.3"
  },
  "crons": [
    {
      "path": "/api/cron",
      "schedule": "* * * * *"
    }
  ]
}

Last updated on March 4, 2025

Build Output API

Features

Was this helpful?

Build Output Configuration

Source route: MatchableValue

Source route: HasField

Source route: Locale

Source route: Mitigate

Source route: Transform

Source route: `MatchableValue`

Source route: `HasField`

Source route: `Locale`

Source route: `Mitigate`

Source route: `Transform`