This page will help you create serverless functions compatible with AWS Lambda. This may be useful if you’re looking to migrate Lambda workflows into Netlify with minimal refactoring required.
Before creating a TypeScript function, prepare your project by doing the following:
Add the @netlify/functions module to your project to import typings for TypeScript.
npminstall @netlify/functions
Set up tsconfig.json. We recommend that you enable the properties esModuleInterop and verbatimModuleSyntax in your TypeScript configuration file for better compatibility. During the build process, Netlify automatically loads any tsconfig.json configuration files found in your functions directory, the repository root directory, or the base directory, if set.
To add a serverless function to your project, create a TypeScript file in your functions directory following the instructions below for naming and coding your function. Netlify will access the functions directory during every build, preparing and deploying each supported code file as a function.
You can store your function file directly under the functions directory or in a subdirectory dedicated to the function. The function’s endpoint name is case-sensitive and determined by its filename or the name of its dedicated parent directory.
For example, to create a function with an endpoint name of hello, save the function file in one of the following ways:
netlify/functions/hello.ts
netlify/functions/hello/hello.ts
netlify/functions/hello/index.ts
These formats would deploy a synchronous function that can be called on the following endpoint: /.netlify/functions/hello. The endpoint is relative to the base URL of your site. Here are some example full endpoint URLs: yoursitename.netlify.app/.netlify/functions/hello for a site using the default Netlify subdomain or www.yourcustomdomain.com/.netlify/functions/hello for a site using a custom domain.
To create a background function, append the function name with -background. For example, to create a background function with an endpoint name of hello-background, save the function file in one of these ways:
These formats would deploy a background function that can be called on the following endpoint: /.netlify/functions/hello-background. The endpoint is relative to the base URL of your site. Here are some example full endpoint URLs: yoursitename.netlify.app/.netlify/functions/hello-background for a site using the default Netlify subdomain or www.yourcustomdomain.com/.netlify/functions/hello-background for a site using a custom domain.
Reserved names for event-driven functions
Certain function names are reserved as triggers initiated by various built-in events on your Netlify site. You can find a list of these function names and how they work on the page about event-driven functions.
If you import the Handler type as demonstrated in the previous code sample, the event and context arguments and the response are typed accordingly.
Alternatively, you can import the types HandlerEvent, HandlerContext, and HandlerResponse separately and use them to construct a handler function.
Netlify provides the event and context parameters when the function is invoked.
The event object received by the handler is similar to the following:
{"path":"Path parameter (original URL encoding)","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-encoded"}
The context object received by the handler includes information about the context in which the function was called, like certain Identity user information, for example.
Because async function code returns a promise, we recommend returning a response with at least an HTTP status code instead of allowing the function to time out. Using async in your function code doesn’t automatically designate a function as a background function.
Netlify Functions can stream data to clients as it becomes available, rather than returning a buffered payload at the end of the computation. This lets developers and frameworks create faster experiences by using streaming and partial hydration to get content and interactions in front of people as quickly as possible.
To stream a function’s response:
wrap your handler export with the stream decorator
Here’s a simplified example that you can use to test that your function response streams to the client:
import{ stream }from"@netlify/functions";exportconst handler =stream(async()=>{const encoder =newTextEncoder();const formatter =newIntl.DateTimeFormat("en",{ timeStyle:"medium"});const body =newReadableStream({start(controller){
controller.enqueue(encoder.encode("<html><body><ol>"));let i =0;const timer =setInterval(()=>{
controller.enqueue(
encoder.encode(`<li>Hello at ${formatter.format(newDate())}</li>\n\n`));if(i++>=5){
controller.enqueue(encoder.encode("</ol></body></html>"));
controller.close();clearInterval(timer);}},1000);}});return{
headers:{"content-type":"text/html"},
statusCode:200,
body
};});
For an extended example that demonstrates a more likely response streaming use case, consider this function:
import{ stream }from"@netlify/functions";exportconst handler =stream(async event =>{// Get the request from the request query string, or use a defaultconst pie =
event.queryStringParameters?.pie ??"something inspired by a springtime garden";// The response body returned from "fetch" is a "ReadableStream",// so you can return it directly in your streaming responseconst res =awaitfetch("https://api.openai.com/v1/chat/completions",{
method:"POST",
headers:{"Content-Type":"application/json",// Set this environment variable to your own key
Authorization:`Bearer ${process.env.OPENAI_API_KEY}`},
body:JSON.stringify({
model:"gpt-3.5-turbo",
messages:[{
role:"system",
content:"You are a baker. The user will ask you for a pie recipe. You will respond with the recipe. Use markdown to format your response"},// Use "slice" to limit the length of the input to 500 characters{ role:"user", content: pie.slice(0,500)}],// Use server-sent events to stream the response
stream:true})});return{
headers:{// This is the mimetype for server-sent events"content-type":"text/event-stream"},
statusCode:200,// Pipe the event stream from OpenAI to the client
body: res.body
};});
When invoked this function sends a prompt to OpenAI and streams the response back to the client like a chatbot.
Keep the following limitations in mind when working with streaming functions:
10 second execution limit. If the limit is reached, the response stops streaming.
20 MB response size limit. Responses larger than 20 MB cannot be streamed.
This feature is in Beta and is available on Pro and Enterprise plans.
To create a background function, append the function name with -background. For example, netlify/functions/hello-background.ts or netlify/functions/hello-background/index.ts.
Background function syntax is similar to synchronous function syntax with a couple of key differences:
You will generally pass the function result to a destination other than the originating client.
Background functions don’t support response streaming because they don’t return responses.
Like the synchronous function format, each TypeScript file to be deployed as a background function must import types and export a handler method. As with synchronous function invocation, Netlify provides the event and context parameters when a background function is invoked. Although background functions rely on asynchronous invocation, they don’t require the use of async TypeScript syntax.
Here’s a simplified example background function that you can use to test that your function runs longer than 30 seconds, count-background.ts:
importtype{ BackgroundHandler, HandlerEvent, HandlerContext }from"@netlify/functions";exportconst handler:BackgroundHandler=(event: HandlerEvent, context: HandlerContext)=>{constsleep=(ms:number)=>{returnnewPromise((resolve)=>setTimeout(resolve, ms));};(async()=>{for(let i =0; i <=60; i++){const date =newDate();awaitsleep(1000);console.log(date.toLocaleString(), i);}console.log("Done");})();};
This function deploys to an endpoint at /.netlify/functions/count-background relative to the base URL of your site.
When invoked, the function returns an initial 202 success response.
When successfully executed, the function logs numbers 1 through 60.
Real-time logs only
The Background Functions beta currently supports only real-time logs. You can’t use the function log date filter to explore log history.
For an extended example that demonstrates a more likely background function use case, consider this send-pdf-background.ts function:
import{ jsPDF }from"jspdf";import mailgun from"mailgun-js";importtype{ BackgroundHandler, HandlerEvent }from"@netlify/functions";typeContext={
content:string;
destination:string;};const mg =mailgun({
apiKey: process.env.MAILGUN_API_KEY,
domain: process.env.MAILGUN_DOMAIN,});const handler:BackgroundHandler=async(event: HandlerEvent)=>{if(!event.body){return;}const{ content, destination }=JSON.parse(event.body)as Context;console.log(`Sending PDF report to ${destination}`);const report = Buffer.from(newjsPDF().text(content,10,10).output("arraybuffer"));const info =await mg.messages().send({
from: process.env.MAILGUN_SENDER,
to: destination,
subject:"Your report is ready!",
text:"Details in attached report PDF",
attachments:[{
filename:`report-${newDate().toDateString()}.pdf`,
content: report,
contentType:"application/pdf",},],});console.log(`PDF report sent: %s`, info.id);};export{ handler };
This background function deploys to an endpoint at /.netlify/functions/send-pdf-background relative to the base URL of your site.
When invoked, the function returns an initial 202 success response.
When successfully executed, a PDF report is generated and emailed as an attachment.
Netlify Functions have access to environment variables in the runtime environment. If you have the option to set specific scopes for your environment variables, the scope must include Functions to be available to functions during runtime.
You can also leverage build environment variables to configure how Netlify builds your functions. For example, you can use an environment variable to set the Node.js version.
To optimize build performance, specify function dependencies in the top-level package.json file in the site’s base directory. Here’s an example of a recommended layout:
With continuous deployment, Netlify automatically zips dependencies with your functions for deployment. To do this, Netlify’s build system installs your dependencies and parses each function file to note its dependencies. For each function, Netlify then pulls the required dependencies from the associated node_modules folder and zips them with the function file for deployment. For more details about how this bundling functionality works, visit the repository for the underlying module: @netlify/zip-it-and-ship-it.
Dependencies and bundling
If you are using devDependencies in your package.json file, they won’t be bundled in your functions. We recommend using dependencies instead of devDependencies.
If you’re using a Netlify configuration file to configure custom [functions] settings, note that the node_bundler value for TypeScript functions always overrides to esbuild.
To streamline writing and testing your functions on Netlify, run a local development environment with Netlify Dev. This feature of Netlify CLI includes tools for local function development through a simulated Netlify production environment. The netlify dev command starts a framework server if a framework is detected and handles redirects, proxy rules, environment variables, and Netlify Functions.
To simulate Netlify Functions in a standalone server without the full overhead of Netlify Dev, serve functions locally with the netlify functions:serve CLI command (currently in beta). Then to debug functions, inspect the functions server process.
Push your function source files to your Git provider for continuous deployment where Netlify’s build system automatically detects, builds, and deploys your functions. For more control over the process, learn about other workflows for deploying your functions including custom builds with continuous deployment and manual deploys with the Netlify CLI or API.
Monitor function logs and metrics in the Netlify UI to observe and help troubleshoot your deployed functions.
Netlify function logs are found in the Netlify UI. You can also stream Netlify function logs to the console with the Netlify CLI.
To add a serverless function to your project, create a JavaScript file in your functions directory following the instructions below for naming and coding your function. Netlify will access the functions directory during every build, preparing and deploying each supported code file as a function.
You can store your function file directly under the functions directory or in a subdirectory dedicated to the function. The function’s endpoint name is case-sensitive and determined by its filename or the name of its dedicated parent directory.
For example, to create a function with an endpoint name of hello, save the function file in one of the following ways:
netlify/functions/hello.js
netlify/functions/hello/hello.js
netlify/functions/hello/index.js
These formats would deploy a synchronous function that can be called on the following endpoint: /.netlify/functions/hello. The endpoint is relative to the base URL of your site. Here are some example full endpoint URLs: yoursitename.netlify.app/.netlify/functions/hello for a site using the default Netlify subdomain or www.yourcustomdomain.com/.netlify/functions/hello for a site using a custom domain.
To create a background function, append the function name with -background. For example, to create a background function with an endpoint name of hello-background, save the function file in one of these ways:
These formats would deploy a background function that can be called on the following endpoint: /.netlify/functions/hello-background. The endpoint is relative to the base URL of your site. Here are some example full endpoint URLs: yoursitename.netlify.app/.netlify/functions/hello-background for a site using the default Netlify subdomain or www.yourcustomdomain.com/.netlify/functions/hello-background for a site using a custom domain.
Reserved names for event-driven functions
Certain function names are reserved as triggers initiated by various built-in events on your Netlify site. You can find a list of these function names and how they work on the page about event-driven functions.
To create a synchronous function, use the following general syntax in your JavaScript function file to export a handler method:
exports.handler=asyncfunction(event, context){// your server-side functionality};
Netlify provides the event and context parameters when the function is invoked.
The event object received by the handler is similar to the following:
{"path":"Path parameter (original URL encoding)","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-encoded"}
The context object received by the handler includes information about the context in which the function was called, like certain Identity user information, for example.
Because async function code returns a promise, we recommend returning a response with at least an HTTP status code instead of allowing the function to time out. Using async in your function code doesn’t automatically designate a function as a background function.
Netlify Functions can stream data to clients as it becomes available, rather than returning a buffered payload at the end of the computation. This lets developers and frameworks create faster experiences by using streaming and partial hydration to get content and interactions in front of people as quickly as possible.
To stream a function’s response:
wrap your handler export with the stream decorator
Here’s a simplified example that you can use to test that your function response streams to the client:
const{ stream }=require("@netlify/functions");
exports.handler =stream(async()=>{const encoder =newTextEncoder();const formatter =newIntl.DateTimeFormat("en",{timeStyle:"medium"});const body =newReadableStream({start(controller){
controller.enqueue(encoder.encode("<html><body><ol>"));let i =0;const timer =setInterval(()=>{
controller.enqueue(
encoder.encode(`<li>Hello at ${formatter.format(newDate())}</li>\n\n`));if(i++>=5){
controller.enqueue(encoder.encode("</ol></body></html>"));
controller.close();clearInterval(timer);}},1000);}});return{headers:{"content-type":"text/html"},statusCode:200,
body
};});
For an extended example that demonstrates a more likely response streaming use case, consider this function:
const{ stream }=require("@netlify/functions");
exports.handler =stream(asyncevent=>{// Get the request from the request query string, or use a defaultconst pie =
event.queryStringParameters?.pie ??"something inspired by a springtime garden";// The response body returned from "fetch" is a "ReadableStream",// so you can return it directly in your streaming responseconst res =awaitfetch("https://api.openai.com/v1/chat/completions",{method:"POST",headers:{"Content-Type":"application/json",// Set this environment variable to your own keyAuthorization:`Bearer ${process.env.OPENAI_API_KEY}`},body:JSON.stringify({model:"gpt-3.5-turbo",messages:[{role:"system",content:"You are a baker. The user will ask you for a pie recipe. You will respond with the recipe. Use markdown to format your response"},// Use "slice" to limit the length of the input to 500 characters{role:"user",content: pie.slice(0,500)}],// Use server-sent events to stream the responsestream:true})});return{headers:{// This is the mimetype for server-sent events"content-type":"text/event-stream"},statusCode:200,// Pipe the event stream from OpenAI to the clientbody: res.body
};});
When invoked this function sends a prompt to OpenAI and streams the response back to the client like a chatbot.
Keep the following limitations in mind when working with streaming functions:
10 second execution limit. If the limit is reached, the response stops streaming.
20 MB response size limit. Responses larger than 20 MB cannot be streamed.
This feature is in Beta and is available on Pro and Enterprise plans.
To create a background function, append the function name with -background. For example, netlify/functions/hello-background.js or netlify/functions/hello-background/index.js.
Background function syntax is similar to synchronous function syntax with a couple of key differences:
You will generally pass the function result to a destination other than the originating client.
Background functions don’t support response streaming because they don’t return responses.
Like the synchronous function format, each JavaScript file to be deployed as a background function must export a handler method. As with synchronous function invocation, Netlify provides the event and context parameters when a background function is invoked. Although background functions rely on asynchronous invocation, they don’t require the use of async JavaScript syntax.
Here’s a simplified example background function that you can use to test that your function runs longer than 30 seconds, count-background.js:
exports.handler=function(event, context){functionsleep(ms){returnnewPromise(resolve=>setTimeout(resolve, ms));}asyncfunctiondemo(){for(let i =0; i <60; i++){let date =newDate();awaitsleep(1000);
console.log(date.toLocaleString(), i);}
console.log("Done");}demo();};
This function deploys to an endpoint at /.netlify/functions/count-background relative to the base URL of your site.
When invoked, the function returns an initial 202 success response.
When successfully executed, the function logs numbers 1 through 60.
Real-time logs only
The Background Functions beta currently supports only real-time logs. You can’t use the function log date filter to explore log history.
For an extended example that demonstrates a more likely background function use case, consider this send-pdf-background.js function:
const{ jsPDF }=require("jspdf");const nodemailer =require("nodemailer");const mg =require("nodemailer-mailgun-transport");const transporter = nodemailer.createTransport(mg({auth:{api_key: process.env.MAILGUN_API_KEY,domain: process.env.MAILGUN_DOMAIN}}));
exports.handler=asyncfunction(event){const{ content, destination }=JSON.parse(event.body);
console.log(`Sending PDF report to ${destination}`);const report = Buffer.from(newjsPDF().text(content,10,10).output("arraybuffer"));const info =await transporter.sendMail({from: process.env.MAILGUN_SENDER,to: destination,subject:"Your report is ready!",text:"Details in attached report PDF",attachments:[{filename:`report-${newDate().toDateString()}.pdf`,content: report,contentType:"application/pdf"}]});
console.log(`PDF report sent: ${info.messageId}`);};
This background function deploys to an endpoint at /.netlify/functions/send-pdf-background relative to the base URL of your site.
When invoked, the function returns an initial 202 success response.
When successfully executed, a PDF report is generated and emailed as an attachment.
Netlify Functions have access to environment variables in the runtime environment. If you have the option to set specific scopes for your environment variables, the scope must include Functions to be available to functions during runtime.
You can also leverage build environment variables to configure how Netlify builds your functions. For example, you can use an environment variable to set the Node.js version.
To optimize build performance, specify function dependencies in the top-level package.json file in the site’s base directory. Here’s an example of a recommended layout:
With continuous deployment, Netlify automatically zips dependencies with your functions for deployment. To do this, Netlify’s build system installs your dependencies and parses each function file to note its dependencies. For each function, Netlify then pulls the required dependencies from the associated node_modules folder and zips them with the function file for deployment. For more details about how this bundling functionality works, visit the repository for the underlying module: @netlify/zip-it-and-ship-it.
To streamline writing and testing your functions on Netlify, run a local development environment with Netlify Dev. This feature of Netlify CLI includes tools for local function development through a simulated Netlify production environment. The netlify dev command starts a framework server if a framework is detected and handles redirects, proxy rules, environment variables, and Netlify Functions.
To simulate Netlify Functions in a standalone server without the full overhead of Netlify Dev, serve functions locally with the netlify functions:serve CLI command (currently in beta). Then to debug functions, inspect the functions server process.
Push your function source files to your Git provider for continuous deployment where Netlify’s build system automatically detects, builds, and deploys your functions. For more control over the process, learn about other workflows for deploying your functions including custom builds with continuous deployment and manual deploys with the Netlify CLI or API.
Monitor function logs and metrics in the Netlify UI to observe and help troubleshoot your deployed functions.
Netlify function logs are found in the Netlify UI. You can also stream Netlify function logs to the console with the Netlify CLI.
To add a serverless function to your project, create a Go file in a dedicated function subdirectory in your functions directory following the instructions below for naming and coding your function. Netlify will access the functions directory during every build, preparing and deploying each supported code file as a function.
You must store your function in a subdirectory dedicated to the function. The function’s endpoint name is case-sensitive and determined by the name of its dedicated parent directory.
For example, to create a function with an endpoint name of hello, save the function file in one of the following ways:
netlify/functions/hello/hello.go
netlify/functions/hello/main.go
These formats would deploy a synchronous function that can be called on the following endpoint: /.netlify/functions/hello. The endpoint is relative to the base URL of your site. Here are some example full endpoint URLs: yoursitename.netlify.app/.netlify/functions/hello for a site using the default Netlify subdomain or www.yourcustomdomain.com/.netlify/functions/hello for a site using a custom domain.
To create a background function, append the function name with -background. For example, to create a background function with an endpoint name of hello-background, save the function file in one of these ways:
These formats would deploy a background function that can be called on the following endpoint: /.netlify/functions/hello-background. The endpoint is relative to the base URL of your site. Here are some example full endpoint URLs: yoursitename.netlify.app/.netlify/functions/hello-background for a site using the default Netlify subdomain or www.yourcustomdomain.com/.netlify/functions/hello-background for a site using a custom domain.
Reserved names for event-driven functions
Certain function names are reserved as triggers initiated by various built-in events on your Netlify site. You can find a list of these function names and how they work on the page about event-driven functions.
To create a synchronous function, use the following general syntax in your Go function file. This makes a handler function to receive invocation events:
package main
import("github.com/aws/aws-lambda-go/events""github.com/aws/aws-lambda-go/lambda")funchandler(request events.APIGatewayProxyRequest)(*events.APIGatewayProxyResponse,error){// Your server-side functionality}funcmain(){// Make the handler available for Remote Procedure Call
lambda.Start(handler)}
Here’s a complete example function hello.go:
package main
import("github.com/aws/aws-lambda-go/events""github.com/aws/aws-lambda-go/lambda")funchandler(request events.APIGatewayProxyRequest)(*events.APIGatewayProxyResponse,error){return&events.APIGatewayProxyResponse{
StatusCode:200,
Body:"Hello, World!",},nil}funcmain(){
lambda.Start(handler)}
This function deploys to an endpoint at /.netlify/functions/hello relative to the base URL of your site.
A successful invocation returns the 200 status code and the string, “Hello, World”.
Synchronous functions can return a response object that includes the following information:
This feature is in Beta and is available on Pro and Enterprise plans.
To create a background function, append the function name with -background. For example, netlify/functions/hello-background/hello-background.go or netlify/functions/hello-background/main.go.
Background function syntax is similar to synchronous function syntax, but you will generally pass the function result to a destination other than the originating client. Like the synchronous function format, a Go file to be deployed as a background function must include a handler function to receive invocation events.
Here’s a simplified example background function that you can use to test that your function runs longer than 30 seconds, count-background.go:
package main
import("log""time""github.com/aws/aws-lambda-go/events""github.com/aws/aws-lambda-go/lambda")funchandler(request events.APIGatewayProxyRequest)(*events.APIGatewayProxyResponse,error){for i :=0; i <60; i++{
log.Println(i)
time.Sleep(1* time.Second)}returnnil,nil}funcmain(){
lambda.Start(handler)}
This function deploys to an endpoint at /.netlify/functions/count-background relative to the base URL of your site.
When invoked, the function returns an initial 202 success response.
When successfully executed, the function logs numbers 1 through 60.
Real-time logs only
The Background Functions beta currently supports only real-time logs. You can’t use the function log date filter to explore log history.
When the function is executed, it finds and downloads a user’s Gravatar profile image, resizes the image to three different sizes, and saves these images to the site’s repository.
For more details, visit the example’s repository README. Note that this extended example doesn’t follow the file name requirements described on this page. That is because rather than using Netlify’s default automatic build workflow, this example uses a custom build with continuous deployment to compile save.go to identity-signup-background.
Netlify Functions have access to environment variables in the runtime environment. If you have the option to set specific scopes for your environment variables, the scope must include Functions to be available to functions during runtime.
You can also leverage build environment variables to configure how Netlify builds your functions. For example, you can use an environment variable to set the Node.js version.
To streamline writing and testing your functions on Netlify, run a local development environment with Netlify Dev. This feature of Netlify CLI includes tools for local function development through a simulated Netlify production environment. The netlify dev command starts a framework server if a framework is detected and handles redirects, proxy rules, environment variables, and Netlify Functions.
To simulate Netlify Functions in a standalone server without the full overhead of Netlify Dev, serve functions locally with the netlify functions:serve CLI command.
Push your function source files to your Git provider for continuous deployment where Netlify’s build system automatically detects, builds, and deploys your functions. For more control over the process, learn about other workflows for deploying your functions including custom builds with continuous deployment and manual deploys with the Netlify CLI or API.
Monitor function logs and metrics in the Netlify UI to observe and help troubleshoot your deployed functions.
Netlify function logs are found in the Netlify UI. You can also stream Netlify function logs to the console with the Netlify CLI.