Reference
6 min read

Functions API Reference

Learn about available APIs when working with Vercel Functions.
Table of Contents

Functions are defined similar to a Route Handler in Next.js. When using Next.js App Router, you can define a function in a file under app/api/{example}/route.ts in your project. Vercel will deploy any file under app/api/ as a function.

Vercel Functions use a Web Handler, which consists of the request parameter that is an instance of the web standard Request API, and for non-Next.js apps, a context parameter that represents the context of the request. Next.js extends the standard Request object with additional properties and methods.

To use a Web Handler, you must be using Node.js 18 or later. If you are using an earlier version, you must use the Node.js signature.

ParameterDescriptionNext.jsOther Frameworks
requestAn instance of the Request objectNextRequestRequest
contextAn object containing the context of the requestNext.js doesn't support this parameter. Instead, use waitUntil as import{ waitUntil }
Next.js (/app)
Next.js (/pages)
Other frameworks
app/api/hello/route.ts
export const dynamic = 'force-dynamic'; // static by default, unless reading the request
 
export function GET(request: Request) {
  return new Response(`Hello from ${process.env.VERCEL_REGION}`);
}

The waitUntil() method enqueues an asynchronous task to be performed during the lifecycle of the request. You can use it for anything that can be done after the response is sent, such as logging, sending analytics, or updating a cache, without blocking the response from being sent. waitUntil() is available in the Node.js and Edge Runtime. Promises passed to waitUntil() will have the same timeout as the function itself. If the function times out, the promises will be cancelled.

To use waitUntil() in your function, import the waitUntil() method from @vercel/functions package. For more information, see the @vercel/functions reference.

Alternatively, for non-Next.js functions only, you can also access the waitUntil() method through a second context argument.

Next.js (/app)
Next.js (/pages)
Other frameworks
app/api/hello/route.ts
// Use the @vercel/functions package to import waitUntil
 
import { waitUntil } from '@vercel/functions';
 
export function GET() {
  const country = request.headers.get('x-vercel-ip-country');
  // Returns a response immediately while keeping the function alive
  waitUntil(fetch(`https://api.vercel.app/countries/?incr=${country}`));
  return new Response(`You're visiting from beautiful ${country}`);
}

To configure your function when using the App Router in Next.js, you use segment options, rather than a config object.

app/api/example/route.ts
export const runtime = 'nodejs';
export const maxDuration = 15;

The table below shows a highlight of the valid config options. For detailed information on all the config options, see the Configuring Functions docs.

PropertyTypeDescription
runtimestringThis optional property defines the runtime to use, and if not set the runtime will default to nodejs.
preferredRegionstringThis optional property and can be used to specify the regions in which your function should execute. This can only be set when the runtime is set to edge
maxDurationintThis optional property can be used to specify the maximum duration in seconds that your function can run for. This can't be set when the runtime is set to edge
Last updated on July 24, 2024