@vercel/functions API Reference

Learn about available APIs when working with Vercel Functions.

Table of Contents

Next.js (/app)

Install and use the package

Install the @vercel/functions package:

pnpm

yarn

npm

pnpm i @vercel/functions

Import the @vercel/functions package:

app/api/hello/route.ts

import { waitUntil } from '@vercel/functions';
 
export function GET() {
  ...
}

For OIDC methods, import @vercel/functions/oidc

Helper methods

`waitUntil`

Description: Extends the lifetime of the request handler for the lifetime of the given Promise. See the Functions API Reference to learn more.

Name	Type	Description
`promise`	`Promise`	The promise to wait for.

Import the @vercel/functions package, which exposes the waitUntil() method:

Next.js (/app)

Next.js (/pages)

Other frameworks

app/api/hello/route.ts

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}`);
}

`getEnv`

Description: Gets the System Environment Variables exposed by Vercel.

api/example.ts

import { getEnv } from '@vercel/functions';
 
export function GET(request) {
  const { VERCEL_REGION } = getEnv();
  return new Response(`Hello from ${VERCEL_REGION}`);
}

`geolocation`

Description: Returns the location information for the incoming request, in the following way:

{
  "city": "New York",
  "country": "US",
  "flag": "🇺🇸",
  "countryRegion": "NY",
  "region": "dev1",
  "latitude": "40.7128",
  "longitude": "-74.0060"
}

Name	Type	Description
`request`	`Request`	The incoming request object which provides the IP

api/example.ts

import { geolocation } from '@vercel/functions';
 
export function GET(request) {
  const details = geolocation(request);
  return Response.json(details);
}

`ipAddress`

Description: Returns the IP address of the request from the headers.

Name	Type	Description
`request`	`Request`	The incoming request object which provides the IP

api/example.ts

import { ipAddress } from '@vercel/functions';
 
export function GET(request) {
  const ip = ipAddress(request)
  return new Response('Your ip is' ${ip});
}

OIDC methods

To use OIDC methods, import the @vercel/functions/oidc package:

app/api/hello/route.ts

import { awsCredentialsProvider } from '@vercel/functions/oidc'
 
export function GET() {
  ...
}

`awsCredentialsProvider`

Description: Obtains the Vercel OIDC token and creates an AWS credential provider function that gets AWS credentials by calling the STS AssumeRoleWithWebIdentity API.

Name	Type	Description
`roleArn`	`string`	ARN of the role that the caller is assuming.
`clientConfig`	`Object`	Custom STS client configurations overriding the default ones.
`clientPlugins`	`Array`	Custom STS client middleware plugin to modify the client default behavior.
`roleAssumerWithWebIdentity`	`Function`	A function that assumes a role with web identity and returns a promise fulfilled with credentials for the assumed role.
`roleSessionName`	`string`	An identifier for the assumed role session.
`providerId`	`string`	The fully qualified host component of the domain name of the identity provider.
`policyArns`	`Array`	ARNs of the IAM managed policies that you want to use as managed session policies.
`policy`	`string`	An IAM policy in JSON format that you want to use as an inline session policy.
`durationSeconds`	`number`	The duration, in seconds, of the role session. Defaults to 3600 seconds.

api/example.ts

import * as s3 from '@aws-sdk/client-s3';
import { awsCredentialsProvider } from '@vercel/functions/oidc';
 
const s3Client = new s3.S3Client({
  credentials: awsCredentialsProvider({
    roleArn: process.env.AWS_ROLE_ARN,
  }),
});

Description: Returns the OIDC token from the request context or the environment variable. This function first checks if the OIDC token is available in the environment variable VERCEL_OIDC_TOKEN. If it is not found there, it retrieves the token from the request context headers.

api/example.ts

import { ClientAssertionCredential } from '@azure/identity';
import { CosmosClient } from '@azure/cosmos';
import { getVercelOidcToken } from '@vercel/functions/oidc';
 
const credentialsProvider = new ClientAssertionCredential(
  process.env.AZURE_TENANT_ID,
  process.env.AZURE_CLIENT_ID,
  getVercelOidcToken,
);
 
const cosmosClient = new CosmosClient({
  endpoint: process.env.COSMOS_DB_ENDPOINT,
  aadCredentials: credentialsProvider,
});
 
export const GET = () => {
  const container = cosmosClient
    .database(process.env.COSMOS_DB_NAME)
    .container(process.env.COSMOS_DB_CONTAINER);
  const items = await container.items.query('SELECT * FROM f').fetchAll();
  return Response.json({ items: items.resources });
};

Last updated on September 20, 2024

Functions API Reference

Configuring Functions

Was this helpful?