Build serverless functions with JavaScript

To add a serverless Lambda function to your project functions directory, create a JavaScript file which exports a handler method. The name of the file (without the .js extension) determines the name of the serverless function endpoint.

Tip

You can use either a standalone .js file that exports a handler (e.g. functions/{function_name}.js) or a folder with the same name as a .js file in it that exports a handler (e.g. functions/{function_name}/{function_name}.js).

On deployment, each serverless function can be called from an address relative to the deployed site root: /.netlify/functions/{function_name}. You can also set a serverless function to be triggered by certain Netlify events.

Format

Each JavaScript file to be deployed as a serverless Lambda function must export a handler method with the following general syntax:

exports.handler = function(event, context, callback) {
    // your server-side functionality
}

Netlify provides the event and context parameters when the serverless function is invoked. You provide the callback parameter, which is optional, but recommended.

When you call a serverless function’s endpoint, the handler receives an event object similar to what you would receive from the AWS API Gateway:

{
    "path": "Path parameter",
    "httpMethod": "Incoming request's method name"
    "headers": {Incoming request headers}
    "queryStringParameters": {query string parameters }
    "body": "A JSON string of the request payload."
    "isBase64Encoded": "A boolean flag to indicate if the applicable request payload is Base64-encode"
}

The context parameter includes information about the context in which the serverless function was called, like certain Identity user information, for example.

The callback works much like the same parameter in an AWS Lambda function. Your handler should use the callback to return either an error (as the first parameter) or a response object, such as:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "body": "..."
}

Here’s a simple example serverless function, hello.js:

exports.handler = function(event, context, callback) {
    callback(null, {
    statusCode: 200,
    body: "Hello, World"
    });
}

This serverless function would be called from your site at /.netlify/functions/hello, and on success, would return the 200 status code and the string, “Hello, World”.

Runtime settings

For all sites created on or after December 4, 2019, Netlify uses Node.js 12 as the default runtime for serverless functions written in JavaScript.

You can specify a different runtime version with an environment variable in the Netlify UI. For example, to use Node.js 10 for all future serverless functions deployed, set the variable AWS_LAMBDA_JS_RUNTIME with the value nodejs10.x.

This variable accepts any valid AWS Lambda runtime name for JavaScript.

Deploy to apply changes

Environment variables and runtime settings are applied to functions at deploy time. Always re-deploy your functions to apply new settings.

Deprecation notice

Sites created before December 4, 2019 use the Node.js 8 function runtime by default.

Node.js 8 reaches end of life on December 31, 2019, and AWS Lambda discontinues support for new functions using Node.js 8 on January 6, 2020. At that time, all sites not explicitly set to Node.js 10 or above will use the default Node.js 12 version for all deploys of new or updated functions. Previously deployed functions will continue to operate with the runtime set at the time of deployment.

Tools

We’ve made a few tools to help with writing, testing, and deploying your serverless JavaScript functions on Netlify:

  • Netlify Dev – Netlify CLI includes tools for local function development and streamlined deployment.
  • netlify-lambda – An optional build tool for Netlify Functions. The repository README includes a comparison between Netlify Dev and netlify-lambda.