---
title: Build Output Configuration
product: vercel
url: /docs/build-output-api/configuration
canonical_url: "https://vercel.com/docs/build-output-api/configuration"
last_updated: 2026-07-27
type: conceptual
prerequisites:
- /docs/build-output-api
related:
- /docs/project-configuration/vercel-json
- /docs/rest-api
- /docs/image-optimization
- /docs/domains
- /docs/build-output-api/primitives
summary: Learn about the Build Output Configuration file, which is used to configure the behavior of a Deployment.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---
# Build Output Configuration
**Build Output Configuration File**: `.vercel/output/config.json`
## Related pages
> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.
- [Introducing Vercel Schedules](https://vercel.com/blog/introducing-vercel-schedules)
- [Next.js 16.3 support on Vercel](https://vercel.com/blog/vercel-supports-next-js-16-3)
- [Image](https://nextjs.org/docs/pages/api-reference/components/image) — Optimize Images in your Next.js Application using the built-in `next/image` Component.
- [Image Component](https://nextjs.org/docs/app/api-reference/components/image) — Optimize Images in your Next.js Application using the built-in `next/image` Component.
- [Image (Legacy)](https://nextjs.org/docs/pages/api-reference/components/image-legacy) — Backwards compatible Image Optimization with the Legacy Image component.
- [How to reduce Vercel Image Optimization costs](https://vercel.com/kb/guide/reduce-image-optimization-costs-on-vercel) — Learn how to reduce Vercel Image Optimization costs in Next.js by tuning cache TTLs, image sizes, formats, and quality.
- [opengraph-image and twitter-image](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/opengraph-image) — API Reference for the Open Graph Image and Twitter Image file conventions.
- [Programmatic Configuration with vercel.ts](https://vercel.com/docs/project-configuration/vercel-ts) — Define your Vercel configuration in vercel.ts with @vercel/config for type-safe routing and build settings.
- [SvelteKit on Vercel](https://vercel.com/docs/frameworks/full-stack/sveltekit) — Deploy SvelteKit applications to Vercel and configure the adapter, rendering, streaming, ISR, analytics, and Routing Mid
- [Features](https://vercel.com/docs/build-output-api/features) — Learn how to implement common Vercel platform features through the Build Output API.
- [Open Graph \\(OG\\) Image Generation](https://vercel.com/docs/og-image-generation) — Learn how to optimize social media image generation through the Open Graph Protocol and @vercel/og library.
- [Advanced Configuration](https://vercel.com/docs/functions/configuring-functions/advanced-configuration) — Learn how to add utility files to the /api directory, and bundle Vercel Functions.
Full cross-link map for this page: [/docs/build-output-api/configuration.graph.md](/docs/build-output-api/configuration.graph.md)
Schema (as TypeScript):
```ts
type Config = {
version: 3;
routes?: Route[];
images?: ImagesConfig;
wildcard?: WildcardConfig;
overrides?: OverrideConfig;
cache?: string[];
framework?: Framework;
crons?: CronsConfig;
services?: Service[];
daemons?: DaemonsConfig;
};
```
Config Types:
- [Route](#routes)
- [ImagesConfig](#images)
- [WildcardConfig](#wildcard)
- [OverrideConfig](#overrides)
- [CronsConfig](#crons)
- [Service](#services)
- [DaemonsConfig](#daemons)
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
**Build Output Configuration File**: `.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
```json
"version": 3
```
### routes
**Build Output Configuration File**: `.vercel/output/config.json`
[`vercel/examples/build-output-api/routes`](https://github.com/vercel/examples/tree/main/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](/docs/project-configuration/vercel-json#routes).
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.
```ts
type Route = Source | Handler;
```
#### `Source` route
```ts
type Source = {
src: string;
dest?: string;
headers?: Record;
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](/docs/rest-api#types) | Required | Description |
| -------------------- | ----------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **src** | [String](/docs/rest-api#types) | Yes | A PCRE-compatible regular expression that matches each incoming pathname (excluding querystring). |
| **dest** | [String](/docs/rest-api#types) | 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](/docs/rest-api#types) | No | A set of headers to apply for responses. |
| **methods** | [String\[\]](/docs/rest-api#types) | 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](/docs/rest-api#types) | No | A boolean to change matching behavior. If true, routing will continue even when the src is matched. |
| **caseSensitive** | [Boolean](/docs/rest-api#types) | No | Specifies whether or not the route `src` should match with case sensitivity. |
| **check** | [Boolean](/docs/rest-api#types) | No | If `true`, the route triggers `handle: 'filesystem'` and `handle: 'rewrite'` |
| **status** | [Number](/docs/rest-api#types) | 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\[\]](/docs/rest-api#types) | No | A list containing the original routes used to generate the `middlewarePath`. |
| **middlewarePath** | [String](/docs/rest-api#types) | 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`
```ts
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](/docs/rest-api#types) | Required | Description |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------- |
| **eq** | [String](/docs/rest-api#types) \| [Number](/docs/rest-api#types) | No | Value must equal this exact value. |
| **neq** | [String](/docs/rest-api#types) | No | Value must not equal this value. |
| **inc** | [String\[\]](/docs/rest-api#types) | No | Value must be included in this array. |
| **ninc** | [String\[\]](/docs/rest-api#types) | No | Value must not be included in this array. |
| **pre** | [String](/docs/rest-api#types) | No | Value must start with this prefix. |
| **suf** | [String](/docs/rest-api#types) | No | Value must end with this suffix. |
| **re** | [String](/docs/rest-api#types) | No | Value must match this regular expression. |
| **gt** | [Number](/docs/rest-api#types) | No | Value must be greater than this number. |
| **gte** | [Number](/docs/rest-api#types) | No | Value must be greater than or equal to this number. |
| **lt** | [Number](/docs/rest-api#types) | No | Value must be less than this number. |
| **lte** | [Number](/docs/rest-api#types) | No | Value must be less than or equal to this number. |
##### Source route: `HasField`
```ts
type HasField = Array<
| { type: 'host'; value: string | MatchableValue }
| {
type: 'header' | 'cookie' | 'query';
key: string;
value?: string | MatchableValue;
}
>;
```
| Key | [Type](/docs/rest-api#types) | Required | Description |
| --------- | ----------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- |
| **type** | "host" \| "header" \| "cookie" \| "query" | Yes | Determines the HasField type. |
| **key** | [String](/docs/rest-api#types) | No\* | Required for header, cookie, and query types. The key to match against. |
| **value** | [String](/docs/rest-api#types) \| MatchableValue | No | The value to match against using string or MatchableValue conditions. |
##### Source route: `Locale`
```ts
type Locale = {
redirect?: Record;
cookie?: string;
};
```
| Key | [Type](/docs/rest-api#types) | Required | Description |
| ------------ | ----------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **redirect** | [Map](/docs/rest-api#types) | No | An object of keys that represent locales to check for (`en`, `fr`, etc.) that map to routes to redirect to (`/`, `/fr`, etc.). |
| **cookie** | [String](/docs/rest-api#types) | No | Cookie name that can override the Accept-Language header for determining the current locale. |
##### Source route: `Mitigate`
```ts
type Mitigate = {
action: 'challenge' | 'deny';
};
```
| Key | [Type](/docs/rest-api#types) | Required | Description |
| ---------- | ----------------------------------------------------------------------- | -------- | --------------------------------------------- |
| **action** | "challenge" \| "deny" | Yes | The action to take when the route is matched. |
##### Source route: `Transform`
```ts
type Transform =
| {
type: 'request.headers' | 'request.query' | 'response.headers';
op: 'append' | 'set' | 'delete';
target: {
key: string | Omit; // re is not supported for transforms
};
args?: string | string[];
}
| {
type: 'request.path';
op: 'set';
args: string; // a single string; an array is rejected
};
```
| Key | [Type](/docs/rest-api#types) | Required | Description |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------- |
| **type** | "request.headers" \| "response.headers" \| "request.query" \| "request.path" | Yes | The type of transform to apply. |
| **op** | "append" \| "set" \| "delete" | Yes | The operation to perform on the target. The `request.path` transform only supports `set`. |
| **target** | `{ key: string \| Omit }` | No | The target of the transform. Regular expression matching is not supported. Not used for `request.path` transforms. |
| **args** | [String](/docs/rest-api#types) \| [String\[\]](/docs/rest-api#types) | No | The arguments to pass to the transform. For `request.path`, this must be a single `String` that overrides the path the runtime observes (`req.url`). It must start with `/`, must not be scheme-relative, and must not contain a query string, whitespace, or control characters. |
#### 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.
```ts
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](/docs/rest-api#types) | Required | Description |
| ---------- | ----------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| **handle** | HandleValue | Yes | The phase of routing when all subsequent routes should apply. |
| **src** | [String](/docs/rest-api#types) | No | A PCRE-compatible regular expression that matches each incoming pathname (excluding querystring). |
| **dest** | [String](/docs/rest-api#types) | No | A destination pathname or full URL, including querystring, with the ability to embed capture groups as $1, $2. |
| **status** | [Number](/docs/rest-api#types) | 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:
```json
"routes": [
{
"src": "/redirect",
"status": 308,
"headers": { "Location": "https://example.com/" }
}
]
```
### images
**Build Output Configuration File**: `.vercel/output/config.json`
[`vercel/examples/build-output-api/image-optimization`](https://github.com/vercel/examples/tree/main/build-output-api/image-optimization)
The `images` property defines the behavior of Vercel's native [Image Optimization API](/docs/image-optimization), which allows on-demand optimization of images at runtime.
```ts
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](/docs/rest-api#types) | Required | Description |
| -------------------------- | ----------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **sizes** | [Number\[\]](/docs/rest-api#types) | Yes | Allowed image widths. |
| **domains** | [String\[\]](/docs/rest-api#types) | 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\[\]](/docs/rest-api#types) | No | Allowed image qualities. Leave undefined to allow all possibilities, 1 to 100. |
| **minimumCacheTTL** | [Number](/docs/rest-api#types) | No | Cache duration (in seconds) for the optimized images. |
| **formats** | ImageFormat\[] | No | Supported output image formats |
| **dangerouslyAllowSVG** | [Boolean](/docs/rest-api#types) | No | Allow SVG input image URLs. This is disabled by default for security purposes. |
| **contentSecurityPolicy** | [String](/docs/rest-api#types) | No | Change the [Content Security Policy](https://developer.mozilla.org/docs/Web/HTTP/CSP) of the optimized images. |
| **contentDispositionType** | [String](/docs/rest-api#types) | 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:
```json
"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"
}]
}
```
#### API
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](/docs/rest-api#types) | Required | Example | Description |
| ------- | ----------------------------------------------------------------------- | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **url** | [String](/docs/rest-api#types) | 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](/docs/rest-api#types) | 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](/docs/rest-api#types) | Yes | `75` | The quality that the source image should be reduced to. Must be between 1 (lowest quality) to 100 (highest quality). |
### wildcard
**Build Output Configuration File**: `.vercel/output/config.json`
[`vercel/examples/build-output-api/wildcard`](https://github.com/vercel/examples/tree/main/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](#routes).
Each of the domain names specified in the `wildcard` configuration will need to
be assigned as [Production Domains in the Project Settings](/docs/domains).
```ts
type WildCard = {
domain: string;
value: string;
};
type WildcardConfig = Array;
```
#### `wildcard` supported properties
Objects contained within the `wildcard` configuration support the following properties:
| Key | [Type](/docs/rest-api#types) | Required | Description |
| ---------- | ----------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------- |
| **domain** | [String](/docs/rest-api#types) | Yes | The domain name to match for this wildcard configuration. |
| **value** | [String](/docs/rest-api#types) | 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:
```json
"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
**Build Output Configuration File**: `.vercel/output/config.json`
[`vercel/examples/build-output-api/overrides`](https://github.com/vercel/examples/tree/main/build-output-api/overrides)
The `overrides` property allows for overriding the output of one or more [static files](/docs/build-output-api/primitives#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.
```ts
type Override = {
path?: string;
contentType?: string;
};
type OverrideConfig = Record;
```
#### `overrides` supported properties
Objects contained within the `overrides` configuration support the following properties:
| Key | [Type](/docs/rest-api#types) | Required | Description |
| --------------- | ----------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| **path** | [String](/docs/rest-api#types) | No | The URL path where the static file will be accessible from. |
| **contentType** | [String](/docs/rest-api#types) | 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:
```json
"overrides": {
"blog.html": {
"path": "blog"
}
}
```
### cache
**Build Output Configuration File**: `.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.
```ts
type Cache = string[];
```
#### `cache` example
```json
"cache": [
".cache/**",
"node_modules/**"
]
```
### framework
**Build Output Configuration File**: `.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.
```ts
type Framework = {
version: string;
};
```
#### `framework` example
```json
"framework": {
"version": "1.2.3"
}
```
### crons
**Build Output Configuration File**: `.vercel/output/config.json`
The optional `crons` property is an object describing the [cron jobs](/docs/cron-jobs) for the production deployment of a project.
Cron Jobs are a legacy feature and will be migrated to
Schedules
in the future. Schedules include timezones, private function and queue targets. You can also create schedules at runtime.
Migrate your Cron Jobs to Schedules
.
```ts
type Cron = {
path: string;
schedule: string;
};
type CronsConfig = Cron[];
```
#### `crons` example
```json
"crons": [{
"path": "/api/cron",
"schedule": "0 0 * * *"
}]
```
### services
**Build Output Configuration File**: `.vercel/output/config.json`
The optional `services` property is an array of the service build targets in the deployment. When it is present, Vercel reads each service's build output from `.vercel/output/services/`. For the directory structure and routing behavior, see the [Services](/docs/build-output-api/services) reference.
```ts
type Service = {
name: string;
root: string;
framework?: string;
runtime?: string;
entrypoint?: string;
bindings?: ServiceBinding[];
};
type ServiceBinding = {
type: 'service';
service: string;
format: 'url';
env: string;
};
```
| Key | [Type](/docs/rest-api#types) | Required | Description |
| -------------- | ----------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **name** | [String](/docs/rest-api#types) | Yes | The service name. Vercel reads the service's build output from `.vercel/output/services/`. |
| **root** | [String](/docs/rest-api#types) | Yes | Path to the service root, relative to the project root. |
| **framework** | [String](/docs/rest-api#types) | No | The framework detected or configured for the service. |
| **runtime** | [String](/docs/rest-api#types) | No | The runtime detected or configured for the service. |
| **entrypoint** | [String](/docs/rest-api#types) | No | The service entrypoint, relative to the service root. |
| **bindings** | ServiceBinding\[] | No | Caller-side bindings that let this service call another service. See [Service bindings](/docs/services/bindings). |
#### `services` example
```json
"services": [
{
"name": "web",
"root": "web/",
"bindings": [
{
"type": "service",
"service": "api",
"format": "url",
"env": "API_URL"
}
]
},
{
"name": "api",
"root": "api/",
"entrypoint": "main:app"
}
]
```
For an example of declaring services and the resulting build output, see the [Services](/docs/build-output-api/services) reference.
### daemons
**Build Output Configuration File**: `.vercel/output/config.json`
The optional `daemons` property is an object whose keys are the names of the deployment's [daemons](/docs/daemons). Each value is an empty object. When `daemons` is present, Vercel reads each daemon's descriptor from `.vercel/output/daemons//.vc-config.json`, and treats the object as the complete set of daemons for the deployment. Omitting `daemons` means the deployment declares no daemons. For the descriptor format, see the [Daemons](/docs/build-output-api/daemons) reference.
```ts
type DaemonsConfig = Record>;
```
#### `daemons` example
```json
"daemons": {
"worker": {},
"scheduler": {}
}
```
## Full `config.json` example
```json
{
"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": "* * * * *"
}
]
}
```
---
[View full sitemap](/docs/sitemap)
If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.