Using the Node.js Runtime with Vercel Functions

Use the Node.js runtime to run Vercel Functions written in JavaScript or TypeScript.

Node.js-powered functions are suited to computationally intense or large functions and provide benefits like:

• More RAM and CPU power: For computationally intense workloads, or functions that need the Node.js bundle size limits, this runtime is ideal
• Complete Node.js compatibility: The Node.js runtime offers access to all Node.js APIs, making it a powerful tool for many applications

Vercel creates a separate function for each supported source file in the root api/ directory. Avoid creating a separate function for each API endpoint. Keep related routes in a shared function so Fluid compute can reuse instances across routes and Vercel builds fewer functions.

You can use a framework with routing support, such as Hono, or define a single fetch handler that receives requests for all HTTP methods and routes them by URL pathname. Keep shared utilities and route modules outside api/ and import them from your function entry point.

Create a shared API entry point in the root api/ directory using the fetch Web Standard export. As your API grows, add routing logic to this handler and configure rewrites to send related API paths to the same function:

export default {
  fetch(request: Request) {
    return new Response('Hello from Vercel!');
  },
};

Alternatively, you can export each HTTP method as a separate export instead of using the fetch Web Standard export:

export function GET(request: Request) {
  return new Response('Hello from Vercel!');
}

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 page.

Vercel 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 bun.lock or bun.lockb is present, bun install is executed
• If yarn.lock is present yarn install is executed
• If pnpm-lock.yaml is present, pnpm install is executed
  • See supported package managers for pnpm detection details
• If package-lock.json is present, npm install is executed
• If vlt-lock.json is present, vlt install is executed
• Otherwise, npm install is executed

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

The Node.js runtime supports TypeScript files inside the /api directory.

An example TypeScript file that exports a Web signature handler is as follows:

export default {
  async fetch(request: Request) {
    const url = new URL(request.url);
    const name = url.searchParams.get('name') || 'World';
 
    return Response.json({ message: `Hello ${name}!` });
  },
};

You can 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 Vercel 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 Vercel Functions. These methods are:

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

import { VercelRequest, VercelResponse } from "@vercel/node";
 
module.exports = (request: VercelRequest, response: VercelResponse) => {
  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' });
}

Request cancellation must be enabled on a per-route basis. See Functions API Reference for more information.

You can listen for the error event on the request object to detect request cancellation:

import { VercelRequest, VercelResponse } from '@vercel/node';
 
export default async (request: VercelRequest, response: VercelResponse) => {
  let cancelled = false;
  request.on('error', (error) => {
    if (error.message === 'aborted') {
      console.log('request aborted');
    }
    cancelled = true;
  });
 
  response.writeHead(200);
 
  for (let i = 1; i < 5; i++) {
    if (cancelled) {
      // the response must be explicitly ended
      response.end();
      return;
    }
 
    response.write(`Count: ${i}\n`);
 
    await new Promise((resolve) => setTimeout(resolve, 1000));
  }
 
  response.end('All done!');
};

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.