Serverless Functions

Serverless Functions enable developers to write functions in JavaScript and other languages to handle user authentication, form submissions, database queries, custom Slack commands, and more.

These Functions are co-located with your code and part of your Git workflow. As traffic increases, they automatically scale up and down to meet your needs, helping you to avoid downtime and paying for always-on compute.

Serverless Functions location within Vercel infrastructure.

Serverless Functions can be deployed to dozens of regions across the world. You can deploy them to a single region or to multiple regions to improve latency and availability.

The examples below echo the body, path query, and cookies, passed with the request object, as a JSON object using helper methods provided through the Request and Response objects.

import { NextApiRequest, NextApiResponse } from 'next';

export default function handler(
  request: NextApiRequest,
  response: NextApiResponse,
) {
  response.status(200).json({
    body: request.body,
    query: request.query,
    cookies: request.cookies,
  });
}

For all supported languages, see the Supported Languages for Serverless Functions documentation.

More examples of applications you can deploy paired with Serverless Functions can be found in the Vercel repository on GitHub.

You can use Environment Variables inside your Serverless Functions, both locally with vercel dev as well as deployed to Preview and Production environments.

For example, create an .env file locally:

CLIENT_ID="your-value"
CLIENT_SECRET"your-value"

.env.local is not currently supported with vercel dev, so ensure you are using .env. You should not commit this file to git. Ensure .env is added to your .gitignore file.

Then, you can access Environment Variables inside your Function when using vercel dev:

import { NextApiRequest, NextApiResponse } from 'next';

export default function handler(
  request: NextApiRequest,
  response: NextApiResponse,
) {
  const res = await fetch('...', {
    method: 'POST',
    body: JSON.stringify({
      client_id: process.env.CLIENT_ID,
      client_secret: process.env.CLIENT_SECRET,
    }),
    headers: { 'Content-Type': 'application/json' },
  });

  const data = await res.json();
  return response.status(200).json({ data });
}

Using Environment Variables in your Serverless Function.

Finally, add your Environment Variables to your Project Settings for use in Preview and Production environments.

You can use path segments through file names instead of a complex routes file when using Serverless Functions on Vercel.

By using square brackets (e.g. [name].js), you can retrieve dynamic values from the page segment of the URL inside your Serverless Function. For example:

import { NextApiRequest, NextApiResponse } from 'next';

export default function handler(
  request: NextApiRequest,
  response: NextApiResponse,
) {
  // pages/api/[name].ts -> /api/lee
  // req.query.name -> "lee"
  const { name } = request.query;
  return response.end(`Hello ${name}!`);
}

Using Path Segments in your Serverless Function.

Serverless Functions on Vercel enforce a maximum execution timeout. This means that the function must respond to an incoming HTTP request before the timeout has been reached.

If the Serverless Function does not respond to the HTTP request within the timeout, then a 504 error status code is returned with the error code FUNCTION_INVOCATION_TIMEOUT.

The timeout is determined by the "Serverless Function Execution Timeout (Seconds)" limit, which is based on the plan that the Personal Account, or Team has enabled when creating the deployment.

If you are seeing an execution timeout error, check the following possible causes:

• The function isn't returning a response: The function must return an HTTP response, even if that response is an error. If no response is returned, the function will time out.
• The function is taking too long to process a request: Check that any API, or database requests you make in your function, are responding within the "Serverless Function Execution Timeout (Seconds)" limit applicable to your plan.
• You have an infinite loop within your function: Check that your function is not making an infinite loop at any stage of execution.
• Upstream errors: Check that any external API or database that you are attempting to call doesn't have any errors.

Logs are treated as an "error" when Serverless Functions do not return a correct response by either crashing or timing out. The last 2,000 error logs are stored and persisted indefinitely.

next dev

Each deployment at Vercel has a Functions section where you can see the calls to your Serverless Functions in real time. In order to log the functions properly, leave the Functions section open while your deployment is being accessed in the browser.

View of function activity (real-time) in the deployment.

Using the dropdown menu you can filter the logs so only a specific function is being shown. This dropdown mainly shows all the paths defined by the files placed under the /api folder.

When a Serverless Function on a specific path receives a user request, you may see more than one lambda log when the application renders or regenerates the page.

This can occur in the following situations:

1. When a new page is rendered
2. When you are using Incremental Static Regeneration (ISR)

In the case of ISR, multiple logs are the result of:

• A stale page having to be regenerated
• On-demand ISR happening with fallback set as blocking

For a stale page, it happens because there are two things that need to be rendered:

1. The HTML, which is used when you navigate to the page URL in your browser
2. The JSON, which is used when you navigate to the page via a link as a Single Page App (SPA) transition

Both the HTML and JSON need to be in sync and rendered at the same time. Otherwise, you will see different behavior between browser navigation and a SPA transition.

For on-demand ISR, the following happens:

• Synchronous rendering to load the page (HTML, for example) on-demand when it was requested
• Revalidate the 2 versions (HTML, JSON) in the background

In Next.js projects, the functions listed are those API Routes defined by the files placed in pages/api folder. However those pages that require server side rendering, mainly by calling getServerSideProps, will also be available both in the filter drop down and the real time logs.

In order to optimize resources, there is an internal process that bundles as many Serverless Functions as possible into a single Lambda. Such a feature is currently only enabled for Next.js, but it will be enabled in other scenarios in the future.

This internal process shouldn't affect the developer in any case. However, if a configuration via the functions property is present in current versions of Next.js (>= v10.0.9), then the internal process will bundle functions based on the configuration first. The remaining functions will be bundled together optimizing for how many functions are created. In the following example, pages/api/hello.js will be bundled separately from pages/api/another.js since each has a different configuration.

{
  "functions": {
    "pages/api/hello.js": {
      "memory": 3008,
      "maxDuration": 60
    },
    "pages/api/another.js": {
      "memory": 1024,
      "maxDuration": 30
    }
  }
}

An example of a Serverless Function configuration.

For an advanced configuration, you can create a vercel.json file to use Runtimes and other customizations. To view more about the properties you can customize, review the advanced usage section of Runtimes and Project config with vercel.json.

Serverless Functions are allocated CPU power according to the amount of memory configured for them.

For example, with 1,792MB memory configured, a Serverless Function will have the equivalent of one vCPU.

• Serverless Function Size
• Serverless Function Memory
• Serverless Function Concurrency
• Serverless Function Payload Size Limit
• Serverless Function Duration
• Comparison with Edge Functions

For more information on what to do next, we recommend the following articles: