Serverless Functions

With Vercel, you can deploy Serverless Functions, which are pieces of code written with backend languages that take an HTTP request and provide a response.

You can use Serverless Functions to handle user authentication, form submission, database queries, custom slack commands, and more.

Creating Serverless Functions

To create a Serverless Function, create a file in an /api directory from your project root with the appropriate language extension.

Note: If you are using Next.js, use the /pages/api directory instead.
Read more about API functionality with Next.js.

For example, to create a TypeScript function, you can create a file called get-user.ts like below.

import { NowRequest, NowResponse } from '@vercel/node'

export default (req: NowRequest, res: NowResponse) => {
  res.json({ name: 'John', email: 'john@example.com' })
}

A TypeScript Serverless Function that returns a JSON response.

When a user visits /api/get-user, they will receive the JSON from above. Note that you don't have to explicitly set up any routing rules for this to work. By default, filesystem routing is leveraged.

Deploying Serverless Functions

To deploy Serverless Functions without any additional configuration, you can put files with extensions matching supported languages and exported functions in the /api directory at your project's root.

Note: If you are using Next.js, use the /pages/api directory instead.
Read more about API functionality with Next.js.

Then, push to your connected Git repository using a Vercel for Git Integration to receive a deployment automatically.

An Example Node.js Serverless Function

To deploy a serverless Node.js API, provide a main export function like the following, in a .js file within the /api directory:

module.exports = (req, res) => {
  res.json({
    body: req.body,
    query: req.query,
    cookies: req.cookies,
  })
}

An example Node.js Serverless Function using Express.js-like helper methods from the Request and Response objects.

The above example echoes the body, path query, and cookies, passed with the request object, as a JSON object using helper methods provided through the Request and Response.

Then, all you need to do, to have a live API, is push to your connected Git repository using a Vercel for Git Integration to receive a deployment automatically.

The resulting deployment will contain your Node.js Serverless Function and will provide you with a URL like the following, with your API ready to go: https://node-echo-api.now-examples.now.sh/api/?name=example

More Examples and Supported Languages

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 get started with many of the Vercel examples by deploying them from the Quickstarts section.

Environment Variables

You can configure Environment Variables for your Serverless Functions directly from Project Settings. Check out the Environment Variables section of our Build Step documentation to learn more.

Path Segments

Deploying Serverless Functions with Vercel gives you the ability to use path segments through file names instead of a complex routes file.

Creating a file using any of the supported languages in the /api directory and wrapping the filename in square brackets, such as [name].js will provide you with a file that takes a path segment and gives it to the function when requested with a value.

Note: When using path segments, the value passed is made available to the req.query object under the key used for the file name.

When using path segments, any dynamic filename can be used, this is indicated by the use of square brackets. The filename for the path segment is used solely for the purpose of providing a key name for accessing the value on the req.query object.

For example, creating a name directory (within /api) that contains a [name].js file will allow you to receive the path segment entered when accessing /api/name/your-name on the req.query.name object.

The following Node.js example code could then use the path segment in its functionality when requested:

module.exports = (req, res) => {
  const {
    query: { name },
  } = req

  res.send(`Hello ${name}!`)
}

An example of a Node.js Serverless Function that takes a name path segment and returns a string using it.

The resulting deployment can be found here: https://path-segment-with-node.now-examples.now.sh/api/name/world

Note: Any supported language can utilize path segments.

Local Development

Vercel provides an additional command with Vercel CLI to help you develop Serverless Functions locally by replicating the production environment on Vercel with your localhost.

If you have an api directory like the above examples on this page, you can run the following command to start a local development environment that supports your serverless API and allows you to develop locally, just make sure to install your project's dependencies first with npm install:

vercel dev

Starting a local development environment using Vercel CLI, for Serverless Functions.

Note: The vercel dev command is still in beta. If you have any feedback, please let us know.

If you have a statically generated frontend that supports its own development environment, such as Next.js, we recommend creating a dev script within a package.json file at the root of your project that vercel dev can use and extend:

{
  ...
  "scripts": {
    "dev": "next --port $PORT"
  }
}

Defining a custom dev script for Next.js in a package.json file.

Note: The above script example uses --port $PORT in the dev command. This uses the framework's – in this case Next.js – port argument to pass the port from vercel dev so that it can properly fetch the running framework.