Getting started with serverless functions
Serverless functions provide a way to write server-side code that interacts with HubSpot and third-party services through APIs. APIs requiring authentication are not safe for the front-end of a website, as your credentials would be exposed.
Serverless functions can act as an intermediary between your front-end and back-end services that require authentication. With serverless functions, developers don’t need to spin up and manage new servers. Serverless functions require less overhead and as a result they are easier to scale as a business grows. We have a high level overview of what HubSpot serverless functions are and how they work, we recommend reading through before doing this tutorial.
This tutorial will guide you through the creation of your first serverless function.
You will create a serverless function folder, set up your configuration folder, create a function and get a response from it.
What you should do before taking this tutorial:
- Have access to a CMS Hub Enterprise account or a CMS Developer Sandbox account.
- Ensure you have at least a basic understanding of the concept of what a serverless function is.
- Become familiar with the HubSpot local development tools, as they are required for working with serverless functions.
- Ensure you have the latest version of the HubSpot local development tools.
- You should already have the local development tools authenticated with your HubSpot account.
On your computer, in the folder that contains your
hubspot.config.yml file, create a
serverless-tutorial folder. This folder will contain all of our files, both the functions themselves and a template which will use the function.
In your terminal run the watch command:
This will cause any edits to this folder to result in uploads to the design manager. Since the folder currently has no content, this command will simply state Watcher is ready and watching.
Inside of the
serverless-tutorial folder create a
This is similar to custom modules folders which end in
.functions serves to communicate that folder contains serverless functions. Files stored in this folder are not publicly accessible.
Because this folder is currently empty the
watch command you have running will not create this folder in the Design Manager yet.
Create a new file in your
my-first-function.functions folder, name it
serverless.json is a required file contained within a
.functions folder. It serves as a configuration file for serverless functions. Defining the runtime environment, serverless function version, and available endpoints. For a rundown of everything that gets defined in this file, see our serverless reference.
If you created and saved the file empty, you'll receive an error message in your terminal stating you can't upload an empty
serverless.json file. That's okay, to ignore because you're going to add that code and then save it - triggering a new upload that will suceed.
Paste the code below into your serverless.json:
Save the file.
Keep this file open in your code editor, we will be coming back to it.
watch is running, if you refresh your design manager you will now see your
my-first-function.functions folders and your new
Create a new file in your my-first-function.functions folder, name it congratulation.js
This is the actual function file, the file that will execute and perform a task.
Paste in the code below:
This serverless function when executed returns a string
"Congrats! You just deployed a Serverless Function." and a status code of
200, indicating success.
In a real world scenario it is likely you might use APIs or perform some calculations you don't want public. You would return the result of those calculations or, a simple status code based on how the success of your API transactions.
You are not done yet, there is no way to execute this function just yet.
serverless.json file again. In your file find your
Update the object to look like this:
The endpoints object contains a
"congratulation" is the endpoint you're creating. The endpoint's name is what defines the path that you will use to call your serverless function.
Serverless functions are exposed through a path at your HubSpot CMS account’s domain.
These functions can be accessed at:
In the case of this "congratulation" endpoint you've created, it will be
Because of this it is generally a good idea to name your endpoint similarly to your function file's name, and both should be named based on the information they act against, not the action taken against that information. You should use the HTTP method or methods for communicating the type of action you are making against that information. The "method" parameter defines the HTTP method's your function supports. It can be a single string or an array of strings denoting the methods the function supports.
The simplest way to test a
GET request to your serverless function is to go to your endpoint's URL directly in the browser.
Replacing your-domain.com with your HubSpot site's domain.
You should see
"Congrats! You just deployed a serverless function".
Success, you did it!
If you do not get that response, start from the top of this tutorial carefully reading each step and verifying the code. It is likely instructions in step 4 or 5 were not followed correctly.
Using a new terminal window navigate into your
serverless-tutorial folder using
Run the following command in your terminal:
This creates a
test-function.html file. Open this file in your code editor.
</head> tag add
HubSpot serverless functions only support the content type
application/json. Leaving it out will result in an "Unsupported Media Type" error.
www.example.com to your account's domain.
Save the file.
In the design manager find your
test-function.html file (you may need to refresh)
Right click the file, choose "create page".
Name your page "Test Function". Create page.
Click preview, preview in new window.
Inspect the page by right clicking anywhere on the page and selecting "inspect".
If you did everything correctly you should see in your console the congratulations message.
Congratulations, you've called your serverless function from within a HubSpot CMS page.
hs logs. Check out the local development reference for more information on this command.
What did you do?
You created a serverless function folder, with a serverless.json configuration file, and function file named
Now that you understand how the configuration file, function file, and
.functions folder relate, the CLI has a handy command you can use to create your functions faster next time.
This function creates a
serverless.json file and a function file with the names you provide.
Thank you for your feedback, it means a lot to us.