Deploy a Node.js function

Last updated 5 months ago

Koyeb comes with native support of Node.js functions with continuous deployment features to automatically deploy your code each time you push a new commit.

When deploying a Node.js function, we take care of the complete continuous deployment process for you:

  • During the build process, we build production-ready images and automatically install your Node.js dependencies
  • During the deployment process, we make sure all servers are always up-to-date and ready to handle new events without service disruption

In this documentation, we explain how to configure your git repositories to deploy serverless Node.js functions on Koyeb.

Git repository structure & function deployment

To build and deploy your functions on Koyeb, you need to create a koyeb.yaml file in your git repository. This file is required by Koyeb to build, deploy and determine how your functions are invoked.

In the koyeb.yaml, you must define:

  1. the runtime: the Node.js version used to execute your code
  2. the handler: the Node.js function that will be called each time an event is received
1functions:
2  - name: function1
3    runtime: nodejs14
4    handler: function1.handler
5    ...
6

Your functions are written in .js files. Each JavaScript file to be deployed as a Koyeb function must export a handler method:

1const handler = async (event, context, callback) => {
2  // Your code goes here.
3};
4
5module.exports.handler = handler;
6

Koyeb provides the event and context as parameters when your function is invoked.

If you use non-async handler, a third argument, callback is passed as a parameter. The callback parameter is a function that you can call to send a response in your function.

We recomand to use async handler as the syntax is more versatile.

Below are the minimal requirements needed in your git repository to deploy a Node.js function on Koyeb:

1koyeb-functions
2├── koyeb.yaml
3└── package.json
4└── function1.js
5└── function2.js
6└── function3.js
7

Each time a new commit is pushed, a new Stack revision is created and your functions are built and deployed.

Run your function locally

At the moment, we use Docker to run a function locally. We plan to improve and package the local development environment soon to provide a better experience. To run your function locally type:

1docker run -p 8080:8080 --rm -e KOYEB_HANDLER=function1.handler -v $PWD/hello-world:/var/task -ti koyeb/runtime:nodejs14 --debug
2

This command launches a Docker container using the koyeb/runtime:nodejs14 image (providing a NodeJS version 14 runtime) and listening on the port 8080.

Invoke the function

We use CloudEvents for describing event data in standard formats to provide interoperability across services, platforms, and systems. To invoke the function, you need to pass required HTTP headers to mock the event handled by the function:

  • ce-source: A string representing the event source.
  • ce-type: A string representing the event type.
  • ce-subject: A string representing the event subject.
  • ce-specversion: The CloudEvents spec version
  • ce-id: A string representing the event ID.

For instance to invoke a function with a basic payload, run the following command:

1 curl localhost:8080  -H 'content-type: application/json' -H "ce-specversion: 1.0" -H "ce-source: local-invokation" -H "ce-type: dev" -H "ce-subject: local-function-invokation" -H "ce-id: 1" -d '{"body": "Hello World!"}'
2

In the function definition, you will receive the body in the event parameters and the event details in context:

1const handler = async (event, context) => {
2    // your code here.
3};
4module.exports.handler = handler;
5

Ready to get started?

Get in touch or create an account and deploy your serverless stack in minutes.

footer-frame