Using the Node.js Runtime with Serverless Functions

You can create Vercel Function in JavaScript or TypeScript by using the Node.js runtime. By default, the runtime builds and serves any function created within the /api directory of a project to Vercel.

In order to use this runtime, you only need to create a file inside the api directory. No additional configuration is needed.

There are two ways to create a Node.js function:

• By using the Web signature:
  api/hello.ts

  export function GET(request: Request) {
    return new Response(`Hello from ${process.env.VERCEL_REGION}`);
  }

• Exporting a default function handler, as shown below. By default, these functions don't stream. If you want to force streaming, see Forcing Streaming Functions.
  api/hello.js

  export default function handler(request, response) {
    const { name = 'World' } = request.query;
    return response.send(`Hello ${name}!`);
  }

To learn more about creating Vercel Functions, see the Functions API Reference. If you need more advanced behavior, such as a custom build step or private npm modules, see the Advanced Node.js Usage section.

Serverless Functions using the Node.js runtime support all Node.js APIs, including standard Web APIs such as the Request and Response Objects.

To learn more about the supported Node.js versions on Vercel, see Supported Node.js Versions.

For dependencies listed in a package.json file at the root of a project, the following behavior is used:

• If pnpm-lock.yaml is present, pnpm install is executed
  • If "lockfileVersion": 5.4 is present in the lock file, pnpm 7 is used
  • Otherwise, pnpm 6 is used
• If package-lock.json is present, npm install is executed
  • If "lockfileVersion": 2 is present in the lock file, npm 8 is used
  • Otherwise npm 6 is used
• If bun.lockb is present, the Install Command is bun install
  • Bun 1 is used
• Otherwise, yarn install is executed

If you need to select a specific version of a package manager, see corepack.

The Node.js runtime supports files ending with .ts inside of the /api directory as TypeScript files to compile and serve when deploying.

An example TypeScript file that exports a default Node.js function and takes in the standard Node.js Request and Response objects is as follows:

import type { VercelRequest, VercelResponse } from '@vercel/node';
 
export default function (request: VercelRequest, response: VercelResponse) {
  const { name = 'World' } = request.query;
  response.send(`Hello ${name}!`);
}

The VercelRequest and VercelResponse imports in the above example are types that we provide for the Request and Response objects, including the helper methods with Vercel. These types can be installed from npm with the following command:

npm install @vercel/node --save-dev

You can also use a tsconfig.json file at the root of your project to configure the TypeScript compiler. Most options are supported aside from "Path Mappings" and "Project References".

Each request to a Node.js Serverless Function gives access to Request and Response objects. These objects are the standard HTTP Request and Response objects from Node.js.

Vercel additionally provides helper methods inside of the Request and Response objects passed to Node.js Serverless Functions. These methods are:

The following Node.js Serverless Function example showcases the use of request.query, request.cookies and request.body helpers:

module.exports = (request, response) => {
  let who = 'anonymous';
 
  if (request.body && request.body.who) {
    who = request.body.who;
  } else if (request.query.who) {
    who = request.query.who;
  } else if (request.cookies.who) {
    who = request.cookies.who;
  }
 
  response.status(200).send(`Hello ${who}!`);
};

We populate the request.body property with a parsed version of the content sent with the request when possible.

We follow a set of rules on the Content-type header sent by the request to do so:

With the request.body helper, you can build applications without extra dependencies or having to parse the content of the request manually.

When the request body contains malformed JSON, accessing request.body will throw an error. You can catch that error by wrapping request.body with try...catch:

try {
  request.body;
} catch (error) {
  return response.status(400).json({ error: 'My custom 400 error' });
}

Express.js is a popular framework used with Node.js. For information on how to use Express with Vercel, see the guide: Using Express.js with Vercel.