8 min read

Build Output Configuration

Learn about the Build Output Configuration file, which is used to configure the behavior of a Deployment.
Table of Contents

.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:

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.

.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": 3

.vercel/output/config.json

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;
type Source = {
  src: string;
  dest?: string;
  headers?: Record<string, string>;
  methods?: string[];
  continue?: boolean;
  caseSensitive?: boolean;
  check?: boolean;
  status?: number;
  has?: Array<HostHasField | HeaderHasField | CookieHasField | QueryHasField>;
  missing?: Array<
    HostHasField | HeaderHasField | CookieHasField | QueryHasField
  >;
  locale?: Locale;
  middlewareRawSrc?: string[];
  middlewarePath?: string;
};
KeyTypeRequiredDescription
srcStringYesA PCRE-compatible regular expression that matches each incoming pathname (excluding querystring).
destStringNoA destination pathname or full URL, including querystring, with the ability to embed capture groups as $1, $2, or named capture value $name.
headersMapNoA set of headers to apply for responses.
methodsString[]NoA set of HTTP method types. If no method is provided, requests with any HTTP method will be a candidate for the route.
continueBooleanNoA boolean to change matching behavior. If true, routing will continue even when the src is matched.
caseSensitiveBooleanNoSpecifies whether or not the route src should match with case sensitivity.
checkBooleanNoIf true, the route triggers handle: 'filesystem' and handle: 'rewrite'
statusNumberNoA status code to respond with. Can be used in tandem with Location: header to implement redirects.
hasArray<HostHasField | HeaderHasField | CookieHasField | QueryHasField>NoConditions of the HTTP request that must exist to apply the route.
missingArray<HostHasField | HeaderHasField | CookieHasField | QueryHasField>NoConditions of the HTTP request that must NOT exist to match the route.
localeLocaleNoConditions of the Locale of the requester that will redirect the browser to different routes.
middlewareRawSrcString[]NoA list containing the original routes used to generate the middlewarePath.
middlewarePathStringNoPath to an Edge Runtime function that should be invoked as middleware.
Source Route: Locale
type Locale = {
  redirect?: Record<string, string>;
  cookie?: string;
};
KeyTypeRequiredDescription
redirectMapYesAn object of keys that represent locales to check for (en, fr, etc.) that map to routes to redirect to (/, /fr, etc.).
cookieStringNoCookie name that can override the Accept-Language header for determing the current locale.
Source Route: HostHasField
type HostHasField = {
  type: 'host';
  value: string;
};
KeyTypeRequiredDescription
type"host"YesDetermines the HasField type.
valueStringYesHost name that must match the request URL's host to cause this route to match.
Source Route: HeaderHasField
type HeaderHasField = {
  type: 'header';
  key: string;
  value?: string;
};
KeyTypeRequiredDescription
type"header"YesDetermines the HasField type.
keyStringYesHeader name that must exist on the request for this route to match.
valueStringNoHeader value (or regex) that must match for this route to match.
Source Route: CookieHasField
type CookieHasField = {
  type: 'cookie';
  key: string;
  value?: string;
};
KeyTypeRequiredDescription
type"cookie"YesDetermines the HasField type.
keyStringYesCookie name that must exist on the request for this route to match.
valueStringNoCookie value (or regex) that must match for this route to match.
Source Route: QueryHasField
type QueryHasField = {
  type: 'query';
  key: string;
  value?: string;
};
KeyTypeRequiredDescription
type"query"YesDetermines the HasField type.
keyStringYesQuerystring key to look for.
valueStringNoQuerystring value (or regex) that must match for this route to match.

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;
};
KeyTypeRequiredDescription
handleHandleValueYesThe phase of routing when all subsequent routes should apply.
srcStringNoA PCRE-compatible regular expression that matches each incoming pathname (excluding querystring).
destStringNoA destination pathname or full URL, including querystring, with the ability to embed capture groups as $1, $2.
statusStringNoA status code to respond with. Can be used in tandem with Location: header to implement redirects.

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/" }
    }
  ]

.vercel/output/config.json

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;
};
 
type ImagesConfig = {
  sizes: number[];
  domains: string[];
  remotePatterns?: RemotePattern[];
  minimumCacheTTL?: number; // seconds
  formats?: ImageFormat[];
  dangerouslyAllowSVG?: boolean;
  contentSecurityPolicy?: string;
  contentDispositionType?: string;
};
KeyTypeRequiredDescription
sizesNumber[]YesSupported image widths.
domainsString[]YesAllowed external domains that can use Image Optimization. Leave empty for only allowing the deployment domain to use Image Optimization.
remotePatternsRemotePattern[]NoAllowed external patterns that can use Image Optimization. Similar to domains but provides more control with RegExp.
minimumCacheTTLNumberNoCache duration (in seconds) for the optimized images.
formatsImageFormat[]NoSupported output image formats
dangerouslyAllowSVGBooleanNoAllow SVG input image URLs. This is disabled by default for security purposes.
contentSecurityPolicyStringNoChange the Content Security Policy of the optimized images.
contentDispositionTypeStringNoSpecifies the value of the "Content-Disposition" response header.

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"],
    "remotePatterns": [{
      "protocol": "https",
      "hostname": "^via\\.placeholder\\.com$",
      "pathname": "^/1280x640/.*$"
    }]
  }

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:

KeyTypeRequiredExampleDescription
urlStringYes/assets/me.pngThe URL of the source image that should be optimized. Absolute URLs must match a pattern defined in the remotePatterns configuration.
wIntegerYes200The width (in pixels) that the source image should be resized to. Must match a value defined in the sizes configuration.
qIntegerYes75The quality that the source image should be reduced to. Must be between 1 (lowest quality) to 100 (highest quality).

.vercel/output/config.json

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>;

Objects contained within the wildcard configuration support the following properties:

KeyTypeRequiredDescription
domainStringYesThe domain name to match for this wildcard configuration.
valueStringYesThe value of the $wildcard match that will be available for routes to utilize.

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" }
  ]

.vercel/output/config.json

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>;

Objects contained within the overrides configuration support the following properties:

KeyTypeRequiredDescription
pathStringNoThe URL path where the static file will be accessible from.
contentTypeStringNoThe value of the Content-Type HTTP response header that will be served with the static file.

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

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

.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": [
    ".cache/**",
    "node_modules/**"
  ]

.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": {
    "version": "1.2.3"
  }

.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": [{
    "path": "/api/cron",
    "schedule": "0 0 * * *"
  }]
{
  "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"],
    "remotePatterns": [
      {
        "protocol": "https",
        "hostname": "^via\\.placeholder\\.com$",
        "pathname": "^/1280x640/.*$"
      }
    ]
  },
  "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 February 21, 2024