6 min read

Vercel Primitives

Learn about the Vercel platform primitives and how they work together to create a Vercel Deployment.
Table of Contents

The following directories, code files, and configuration files represent all Vercel platform primitives. These primitives are the "building blocks" that make up a Vercel Deployment.

Files outside of these directories are ignored and will not be served to visitors.

.vercel/output/static

Static files that are publicly accessible from the Deployment URL should be placed in the .vercel/output/static directory.

These files are served with the Vercel Edge Network.

Files placed within this directory will be made available at the root (/) of the Deployment URL and neither their contents, nor their file name or extension will be modified in any way. Sub directories within static are also retained in the URL, and are appended before the file name.

There is no standalone configuration file that relates to static files.

However, certain properties of static files (such as the Content-Type response header) can be modified by utilizing the overrides property of the config.json file.

The following example shows static files placed into the .vercel/output/static directory:

.vercel/output/functions

A Serverless Function is represented on the file system as a directory with a .func suffix on the name, contained within the .vercel/output/functions directory.

Conceptually, you can think of this .func directory as a filesystem mount for a Serverless Function: the files below the .func directory are included (recursively) and files above the .func directory are not included. Private files may safely be placed within this directory because they will not be directly accessible to end-users. However, they can be referenced by code that will be executed by the Serverless Function.

A .func directory may be a symlink to another .func directory in cases where you want to have more than one path point to the same underlying Serverless Function.

A configuration file named .vc-config.json must be included within the .func directory, which contains information about how Vercel should construct the Serverless Function.

The .func suffix on the directory name is not included as part of the URL path of Serverless Function on the Deployment. For example, a directory located at .vercel/output/functions/api/posts.func will be accessible at the URL path /api/posts of the Deployment.

.vercel/output/functions/<name>.func/.vc-config.json

The .vc-config.json configuration file contains information related to how the Serverless Function will be created by Vercel.

type ServerlessFunctionConfig = {
  handler: string;
  runtime: string;
  memory?: number;
  maxDuration?: number;
  environment: Record<string, string>[];
  regions?: string[];
  supportsWrapper?: boolean;
  supportsResponseStreaming?: boolean;
};
KeyTypeRequiredDescription
runtimeStringYesSpecifies which "runtime" will be used to execute the Serverless Function. See Runtimes for more information.
handlerStringYesIndicates the initial file where code will be executed for the Serverless Function.
memoryIntegerNoAmount of memory (RAM in MB) that will be allocated to the Serverless Function. See size limits for more information.
architectureStringNoSpecifies the instruction set "architecture" the Serverless Function supports. Either x86_64 or arm64. The default value is x86_64.
maxDurationIntegerNoMaximum duration (in seconds) that will be allowed for the Serverless Function. See size limits for more information.
environmentMapNoMap of additional environment variables that will be available to the Serverless Function, in addition to the env vars specified in the Project Settings.
regionsString[]NoList of Vercel Regions where the Serverless Function will be deployed to.
supportsWrapperBooleanNoTrue if a custom runtime has support for Lambda runtime wrappers.
supportsResponseStreamingBooleanNoWhen true, the Serverless Function will stream the response to the client.

This extends the Base Config for Node.js Serverless Functions.

type NodejsServerlessFunctionConfig = ServerlessFunctionConfig & {
  launcherType: 'Nodejs';
  shouldAddHelpers?: boolean; // default: false
  shouldAddSourceMapSupport?: boolean; // default: false
};
KeyTypeRequiredDescription
launcherType"Nodejs"YesSpecifies which launcher to use. Currently only "Nodejs" is supported.
shouldAddHelpersBooleanNoEnables request and response helpers methods.
shouldAddSourcemapSupportBooleanNoEnables source map generation.
awsLambdaHandlerStringNoAWS Handler Value for when the serverless function uses AWS Lambda syntax.

This is what the .vc-config.json configuration file could look like in a real scenario:

{
  "runtime": "nodejs16.x",
  "handler": "serve.js",
  "maxDuration": 3,
  "launcherType": "Nodejs",
  "shouldAddHelpers": true,
  "shouldAddSourcemapSupport": true
}

The following example shows a directory structure where the Serverless Function will be accessible at the /serverless URL path of the Deployment:

.vercel/output/functions

An Edge Function is represented on the file system as a directory with a .func suffix on the name, contained within the .vercel/output/functions directory.

The .func directory requires at least one JavaScript or TypeScript source file which will serve as the entrypoint of the function. Additional source files may also be included in the .func directory. All imported source files will be bundled at build time.

WebAssembly (Wasm) files may also be placed in this directory for an Edge Function to import. See Using a WebAssembly file for more information.

A configuration file named .vc-config.json must be included within the .func directory, which contains information about how Vercel should configure the Edge Function.

The .func suffix is not included in the URL path. For example, a directory located at .vercel/output/functions/api/edge.func will be accessible at the URL path /api/edge of the Deployment.

Edge Functions will bundle an entrypoint and all supported source files that are imported by that entrypoint. The following list includes all supported content types by their common file extensions.

  • .js
  • .json
  • .wasm

.vercel/output/functions/<name>.func/.vc-config.json

The .vc-config.json configuration file contains information related to how the Edge Function will be created by Vercel.

type EdgeFunctionConfig = {
  runtime: 'edge';
  entrypoint: string;
  envVarsInUse?: string[];
  regions?: 'all' | string | string[];
};
KeyTypeRequiredDescription
runtime"edge"YesThe runtime: "edge" property is required to indicate that this directory represents an Edge Function.
entrypointStringYesIndicates the initial file where code will be executed for the Edge Function.
envVarsInUseString[]NoList of environment variable names that will be available for the Edge Function to utilize.
regionsString[]NoList of regions or a specific region that the edge function will be available in, defaults to all. View available regions.

This is what the .vc-config.json configuration file could look like in a real scenario:

{
  "runtime": "edge",
  "entrypoint": "index.js",
  "envVarsInUse": ["DATABASE_API_KEY"]
}

The following example shows a directory structure where the Edge Function will be accessible at the /edge URL path of the Deployment:

.vercel/output/functions

A Prerender asset is a Serverless Function that will be cached by the Vercel Edge Network in the same way as a static file. This concept is also known as Incremental Static Regeneration.

On the file system, a Prerender is represented in the same way as a Serverless Function, with an additional configuration file that describes the cache invalidation rules for the Prerender asset.

An optional "fallback" static file can also be specified, which will be served when there is no cached version available.

.vercel/output/functions/<name>.prerender-config.json

The <name>.prerender-config.json configuration file contains information related to how the Edge Function will be created by Vercel.

type PrerenderFunctionConfig = {
  expiration: number | false;
  group?: number;
  bypassToken?: string;
  fallback?: string;
  allowQuery?: string[];
  passQuery?: boolean;
};
KeyTypeRequiredDescription
expirationInteger | falseYesExpiration time (in seconds) before the cached asset will be re-generated by invoking the Serverless Function. Setting the value to false means it will never expire.
groupIntegerNoOption group number of the asset. Prerender assets with the same group number will all be re-validated at the same time.
bypassTokenStringNoRandom token assigned to the __prerender_bypass cookie when Draft Mode is enabled, in order to safely bypass the Edge Network cache
fallbackStringNoName of the optional fallback file relative to the configuration file.
allowQueryString[] | undefinedNoList of query string parameter names that will be cached independently. If an empty array, query values are not considered for caching. If undefined each unique query value is cached independently
passQueryBoolean | undefinedNoWhen true, the query string will be present on the request argument passed to the invoked function. The allowQuery filter still applies.

.vercel/output/functions/<name>.prerender-fallback.<ext>

A Prerender asset may also include a static "fallback" version that is generated at build-time. The fallback file will be served by Vercel while there is not yet a cached version that was generated during runtime.

When the fallback file is served, the Serverless Function will also be invoked "out-of-band" to re-generate a new version of the asset that will be cached and served for future HTTP requests.

This is what an example.prerender-config.json file could look like in a real scenario:

{
  "expiration": 60,
  "group": 1,
  "bypassToken": "03326da8bea31b919fa3a31c85747ddc",
  "fallback": "example.prerender-fallback.html",
  "allowQuery": ["id"]
}

The following example shows a directory structure where the Prerender will be accessible at the /blog URL path of the Deployment:

Last updated on June 22, 2024