Node.js Version

New deployments automatically select the latest LTS Node.js version available on Vercel at that point in time.

In order to select a different version, add a package.json file with an engines field, like so:

{
  "engines": {
    "node": "12.x"
  }
}

Defining the engines property in a package.json file.

When defining an engines property, the following Node.js versions can be selected:

• 10.x
• 12.x (The default if the property is not defined)

In order to find out which Node.js version your deployment is using, run node -v inside it or log the output of process.version.

Node.js Dependencies

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

• If a package-lock.json file is present in the project, npm install is used.
• Otherwise, yarn is used, by default.

Using TypeScript with the Node.js Runtime

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 { NowRequest, NowResponse } from '@vercel/node'

export default function(req: NowRequest, res: NowResponse) {
  const { name = 'World' } = req.query
  res.send(`Hello ${name}!`)
}

An example serverless Node.js function written in TypeScript, using types from the @vercel/node module for the helper methods.

The NowRequest and NowResponse 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

Installing @vercel/node for types when using Node.js on Vercel.

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

Node.js Request and Response Objects

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.

module.exports = (req, res) => {
  let who = 'anonymous'

  if (req.body && req.body.who) {
    who = req.body.who
  } else if (req.query.who) {
    who = req.query.who
  } else if (req.cookies.who) {
    who = req.cookies.who
  }

  res.status(200).send(`Hello ${who}!`)
}

try {
  req.body
} catch (error) {
  return res.status(400).json({ error: 'My custom 400 error' })
}

Go Version

Go version 1.x is used for Go projects deployed with Vercel.

Go Dependencies

The Go Runtime will automatically detect a go.mod file to install dependencies at the root of a project.

Go Build Configuration

You can provide custom build flags by using the GO_BUILD_FLAGS build environment variable.

{
  "build": {
    "env": {
      "GO_BUILD_FLAGS": "-ldflags '-s -w'"
    }
  }
}

An example -ldflags flag with -s -w. This will remove debug information from the output file. This is the default value when no GO_BUILD_FLAGS are provided.

Python Version

Python projects deployed with Vercel use Python version 3.6.

Python Dependencies

You can install dependencies for your Python projects by defining them in a requirements.txt or a Pipfile.lock file.

Ruby Version

New deployments use Ruby 2.7.x as the default version.

You can specify the version of Ruby by defining ruby in a Gemfile, like so:

source "https://rubygems.org"
ruby "~> 2.7.x"

When defining a Ruby version, the following Ruby versions can be selected:

• 2.7.x (default)
• 2.5.x

Ruby Dependencies

This Runtime supports installing dependencies defined in the Gemfile. Alternatively, dependencies can be vendored with the bundler install --deployment command (useful for gems that require native extensions). In this case, dependencies are not built on deployment.

Disabling Helpers for Node.js

Within a vercel.json configuration file at your project's root, use the following build environment variable to disable helpers.

{
  "build": {
    "env": {
      "NODEJS_HELPERS": "0"
    }
  }
}

An example vercel.json file that will turn off the default helpers for your Node.js Serverless Function.

Private npm Modules for Node.js

To install private npm modules, define NPM_TOKEN as a build environment variable in vercel.json.

Alternatively, define NPM_RC as a build environment variable with the contents of ~/.npmrc.

Custom Build Step for Node.js

You can run build tasks by creating a vercel-build script within a package.json file at the entry point's level or higher. For example:

{
  "scripts": {
    "vercel-build": "node ./build.js"
  }
}

An example package.json file with a vercel-build script to execute in the build step.

Along with build script named build.js:

const fs = require('fs')
fs.writeFile('built-time.js', `module.exports = '${new Date()}'`, err => {
  if (err) throw err
  console.log('Build time file created successfully!')
})

An example Node.js file, executed by the above package.json build script.

And a .js file for the built Serverless Functions, index.js inside the /api directory:

const BuiltTime = require('./built-time')
module.exports = (req, res) => {
  res.setHeader('content-type', 'text/plain')
  res.send(`
    This Serverless Function was built at ${new Date(BuiltTime)}.
    The current time is ${new Date()}
  `)
}

An example Node.js Serverless Function, using information from the created file from the build script.

Legacy Serverful Behavior

A Node.js Runtime entrypoint can contain one of the following to retain legacy serverful behavior:

• Default export server, such as module.exports = http.createServer((req, res) => { res.end('hello') }).
• Server listens on a port, such as http.createServer((req, res) => { res.end('hello') }).listen(3000).

AWS Lambda API

The Node.js Runtime provides a way to opt into the AWS Lambda API. This is useful if you have existing Serverless Functions you wish to deploy to Vercel but do not want to change the API.

exports.handler = async function(event, context, callback) {
  return {
    statusCode: 200,
    headers: {},
    body: 'Hello world'
  }
}

{
  "build": {
    "env": {
      "NODEJS_AWS_HANDLER_NAME": "handler"
    }
  }
}

The value of the environment variable needs to match the name of the method that is exported from your Serverless Functions.

Private Packages for Go

To install private packages with go get, define GIT_CREDENTIALS as a build environment variable in vercel.json.

All major Git providers are supported including GitHub, GitLab, Bitbucket, as well as a self-hosted Git server.

With GitHub, you will need to create a personal token with permission to access your private repository.

{
  "build": {
    "env": {
      "GIT_CREDENTIALS": "https://username:token@github.com"
    }
  }
}

An example vercel.json file containing a build environment variable with the value of GitHub credentials.

Web Server Gateway Interface

The Web Server Gateway Interface (WSGI) is a calling convention for web servers to forward requests to web applications written in Python. You can use WSGI with frameworks such as Flask or Django.

Instead of defining a handler, define an app variable in your Python file, when using vercel.json config. For example, define a index.py file inside your project as follows:

from flask import Flask, Response
app = Flask(__name__)

@app.route('/', defaults={'path': ''})
@app.route('/<path:path>')
def catch_all(path):
    return Response("<h1>Flask</h1><p>You visited: /%s</p>" % (path), mimetype="text/html")

An example index.py file, using Flask for a WSGI application.

Inside requirements.txt define:

flask==1.0.2

An example requirements.txt file, listing flask as a dependency.

Asynchronous Server Gateway Interface

The Asynchronous Server Gateway Interface (ASGI) is a calling convention for web servers to forward requests to asynchronous web applications written in Python. You can use ASGI with frameworks such as Sanic.

Instead of defining a handler, define an app variable in your Python file.

For example, define a index.py file inside a folder as follows:

from sanic import Sanic
from sanic.response import json
app = Sanic()


@app.route('/')
@app.route('/<path:path>')
async def index(request, path=""):
    return json({'hello': path})

An example index.py file, using Sanic for a ASGI application.

Inside requirements.txt define:

sanic==19.6.0

An example requirements.txt file, listing sanic as a dependency.

Caching Data

A runtime can retain an archive of up to 100mb of the filesystem at build time. The cache key is generated as a combination of:

• Project name.
• Team id or user id.
• Entrypoint path (e.g., api/users/index.go).
• Runtime identifier including version (e.g.: @vercel/go@0.0.1).

The cache will be invalidated if any of those items changes. The user can bypass the cache by running vercel -f.

Limits

• Runtimes can run for a maximum of 5 minutes before the execution times out.
• The maximum cache archive size of a Runtime is 100mb.
• The cache TTL is 7 days.

Including Additional Files

Most Runtimes use static analysis to determine which source files should be included in the Serverless Function output based on the build src input. Any unused code or assets is ignored to ensure your Serverless Function is as small as possible.

For example, the Node Runtime looks at calls to require() or fs.readFile() in order to determine which files to include automatically.

// index.js
const { readFileSync } = require('fs');
const { join } = require('path');
const file = readFileSync(join(__dirname, 'config', 'ci.yml'), 'utf8');

This /index.js file reads the contents of /config/ci.yml.
The use of __dirname is necessary to read a file relative to the current file.

In some cases, you may wish to include templates or views that are not able to be statically analyzed. Runtimes provide a configuration for includeFiles that accepts a glob of files that will always be included in the Serverless Functions output.

{
  "functions": {
    "api/test.js": {
      "includeFiles": "templates/**"
    }
  }
}

Using the default Node.js language and configuring the includeFiles within a vercel.json configuration file.