In this tutorial, you will learn how to create a Netlify serverless API/function. Creating a serverless API is a key part of creating JAMStack and MACH powered websites. Luckily, creating a serverless API is pretty easy. When I started learning about Netlify serverless functions, one thing I struggled to learn about was how to read data located in a JSON file within the function itself. You may assume you can use NodeJs built-in functions like fs() and path() commands, however, if you try this you will be in a world of hurt. The reason why these functions will not work as you may expect within a serverless function is because of the way Netlify builds the functions. This is why I will also show you how to read JSON data from a file as well. This can be very handy knowledge if you are undertaking a coding test for a job interview. The final thing that I will cover in this tutorial is how to debug your serverless functions locally. Not knowing how to test your function locally will waste your time and will make your workflow inefficient. If this all sounds like things you would like to learn, read on!
How To Create a Netlify Serverless Function
Creating a function is dead simple. Create a folder in your project and call it functions. In here create a file. The name of the file will map to the name of the API in Netlify. The code to create the simplest API possible is shown below:
The code above should be easy to understand. Create an async function and export it using exports.handler. With this simple function created, we can push the function live and test it works! To do this you will need to update netlify.toml. netlify.toml is Netlifys configuration file. If you have not created one in your project yet, create one in the root folder. In this file, you need to tell Netlify where the functions are hosted. This is done using the functions property and looks like this:
How To Debug A Netlify Serverless Function Locally
Assuming you have created a Netlify account and pushed this code into production (tutorial here) this configuration will push a function into production successfully, however, this configuration will not allow you to debug your function locally. Not being able to debug locally is a pain in the bottom, so let us fix that. To debug locally, you will need to install netlify-lambda. This can be done using this command in a terminal, npm install netlify-lambda. After installing the package, you will need to add this command within your package.json file:
Running this command will then launch a new webserver that will launch your functions. This new server will use a different port (usually 5000) compared to your web application. This means you can run your web app and the functions at the same time!
The important thing to understand when using netlify-lambda is the difference in your projects folder structure. You will need to specify a publish directory for the package to run your functions from. This folder needs to be different from the folder where the functions physically live. To be clear, the name of this folder should not be functions. Most tutorials online use a folder name of dist-functions. Due to this configuration, after installing the package and pushing your project into Netlify the build will likely break. To fix this will require an update to netlify.toml. In here you need to set the function path you want to use. Remember do not use the folder name where your functions physically live! Assuming you are happy with using dist-functions as the alias, your netlify.toml should look like this:
You now have everything that you need to configure, run, and debug your functions locally. If you commit everything so it is pushed into Netlify, your API URL will be structured like this:
https://YOUR_APP_NAME.netlify.app/.netlify/functions/YOUR_FUNCTION_FILENAME
Calling the function from a browser should result in the text returned by the function being displayed on the screen. In Netlify you can figure out your function URL like this:
How To Read Data From A JSON file
Finally, I will show you how to read data from a JSON file in a function. The code to do this looks like this:
The code above is pretty simple, however, it took me ages to figure this out. On Line1 I read in the file directly using require. This bit is key, due to the way the server builds the files on Netlify, you need to manually reference files rather than try to read them from a relative folder path. For reference the JSON file looks like this:
On Line2 the return type is set to JSON rather than text. I am also enabling CORS in this function to allow any host to call the API regardless of its origin. This is handy to debug and work on the live API locally. Security-wise this is not ideal, so it is up to you if you want to leave it in. On Line9 we return the data by Stringifying it and adding it to the request body. Being good developers we add a happy status code as well. Job done! Happy Coding 🤘
