Using the Node.js Runtime with Vercel Functions
Learn how to use the Node.js runtime with Vercel Functions to create 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.
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 have bundles up to 250 MB in size, 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
In order to use the Node.js runtime, create a file inside the api
directory with a function using the Web signature. No additional configuration is needed:
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.
The entry point for src
must be a glob matching .js
, .mjs
, or .ts
files** that export a default function.
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
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
- 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
- If
bun.lockb
orbun.lock
is present, the Install Command isbun 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:
export async function GET(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 Serverless Functions. These methods are:
method | description | object |
---|---|---|
request.query | An object containing the request's query string, or {} if the request does not have a query string. | Request |
request.cookies | An object containing the cookies sent by the request, or {} if the request contains no cookies. | Request |
request.body | An object containing the body sent by the request, or null if no body is sent. | Request |
response.status(code) | A function to set the status code sent with the response where code must be a valid HTTP status code. Returns response for chaining. | Response |
response.send(body) | A function to set the content of the response where body can be a string , an object or a Buffer . | Response |
response.json(obj) | A function to send a JSON response where obj is the JSON object to send. | Response |
response.redirect(url) | A function to redirect to the URL derived from the specified path with status code "307 Temporary Redirect". | Response |
response.redirect(statusCode, url) | A function to redirect to the URL derived from the specified path, with specified HTTP status code. | Response |
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}!`);
};
Example Node.js Serverless Function using the request.query
,
request.cookies
, and request.body
helpers. It returns greetings for the
user specified using request.send()
.
If needed, you can opt-out of Vercel providing helpers
using advanced
configuration.
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:
Content-Type header | Value of request.body |
---|---|
No header | undefined |
application/json | An object representing the parsed JSON sent by the request. |
application/x-www-form-urlencoded | An object representing the parsed data sent by with the request. |
text/plain | A string containing the text sent by the request. |
application/octet-stream | A Buffer containing the data sent by the request. |
With the request.body
helper, you can build applications without extra dependencies or having to parse the content of the request manually.
The request.body
helper is set using a JavaScript
getter.
In turn, it is only computed when it is accessed.
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' });
}
Catching the error thrown by request.body
with
try...catch
.
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.
Was this helpful?