Cloud Functions
Launch cloud functions are a mechanism for you to provide backend functionality on your sites, and enable you to write, deploy, and run server-side code on-demand as API endpoints.
These functions are co-located with your frontend code and part of your Git workflow. As traffic increases, they automatically scale up and down to meet your needs.
Example use cases: CRUD operations with database, sending automated email, server-side input validation, etc.
You must code your functions in JavaScript and save them to the /functions directory in your project’s root folder.
The function endpoint is determined by its file path relative to /functions.
Each JavaScript file to be deployed as a cloud function must export a handler function with the following general syntax:
export default function handler(request, response) {
// your server-side functionality
}
Example:
// functions/hello.js
export default function handler(request, response) {
response.status(200).json({
body: request.body,
query: request.query,
cookies: request.cookies,
});
}
The above example returns the request body, path query, and cookies in JSON format.
This function runs when you visit the URL path: /hello
Sometimes you may want to place extra code files, such as utils.js, inside the /functions folder. To skip turning these files into serverless functions, default exporting from such files is not supported. Below is an example of a valid utils.js file that can be placed inside the /functions directory.
Example:
//functions/utils.js
export function getShortName(name) {
return name.slice(0, 3);
}
//functions/user.js
import { getShortName } from "./utils"
export default function handler(request, response) {
const name = "Hilary";
const shortName = getShortName(name);
response.status(200).send({ name, shortName});
}
Node.js Request and Response Objects
Each request to a Launch cloud function gets access to Request and Response objects.
These objects are the standard HTTP Request and Response objects from Node.js.
Node.js Helpers
Additional helpers are provided inside the Request and Response objects passed to the function. These are:
Method | Description | Object |
---|---|---|
req.query | An object containing the request's query string, or {} if the request does not have a query string. | Request |
req.cookies | An object containing the cookies sent by the request, or {} if the request contains no cookies. | Request |
req.body | An object containing the body sent by the request, or null if no body is sent. | Request |
res.status(code) | A function to set the status code sent with the response where the code must be a valid HTTP status code. | Response |
res.send(body) | A function to set the content of the response where the body can be a string, an object, or a Buffer. | Response |
res.json(obj) | A function to send a JSON response where the obj is the JSON object to send. | Response |
res.redirect(url) | A function to redirect to the URL derived from the specified path with status code 307 Temporary Redirect. | Response |
res.redirect(statusCode, url) | A function to redirect to the URL derived from the specified path, with the specified HTTP status code. | Response |
Request Body
The req.body property populates with a parsed version of the content sent with the request when possible, based on the value of the Content-Type header as follows:
Content-Type header | Value of req.body |
---|---|
No header | Undefined |
application/json | An object representing the parsed JSON sent by the request. |
application/x-www-form-urlencoded | An object representing the form data sent with the request. |
text/plain | A string containing the text sent by the request. |
application/octet-stream | A Buffer containing the data sent by the request. |
When the request body contains malformed JSON, accessing req.body will throw an error. You can catch that error by wrapping req.body with try...catch:
try {
const data = req.body;
} catch (error) {
res.status(400).json({ error: 'Invalid JSON in request body' });
}
Handling different HTTP methods
To handle different HTTP methods in a cloud function, you can use req.method in your handler as below:
export default function handler(req, res) {
if (req.method === 'POST') {
// Process a POST request
} else {
// Handle any other HTTP method
}
}
Execution Timeout
Launch cloud functions enforce a maximum execution timeout. This means that the function must respond to an incoming HTTP request before the timeout has been reached. The maximum execution timeout is 30 seconds. If a request times out, the response error code would be 500.
Memory Size
The memory size for a Launch Cloud Function is 1024 MB.
Runtime Environment
The Launch Cloud Functions runtime environment leverages Node.js version 18 to power its execution environment.
File System Support
File system support in Launch Cloud Functions refers to a function's ability to interact with the file system, including read and write operations. Launch Cloud Functions implement a read-only file system, except for the designated /tmp path, which facilitates write operations.
The /tmp path serves as a temporary file system accessible to every Launch Cloud Function, with a storage of up to 500 MB. Note that the data stored in /tmp is non-persistent, as it is automatically deleted upon the termination of the function.
Architecture
Launch Cloud Functions support the x86_64 instruction set.
Dynamic API Routes using Path Segments
Deploying cloud functions with Launch also gives users the ability to use path segments as file names.
When using path segments, any dynamic filename can be used; this is indicated by the use of square brackets ( [ ] ).
Note: The filename for the path segment is used solely for the purpose of providing a key name for accessing the value on the req.query object.
Example: functions/user/[name].js
Here, the value passed for the path segment is made available to the req.query object under the key used for the filename(name).
// functions/user/[name].js
export default function handler(request, response) {
response.send(`Hello ${request.query.name}!`);
}
Running the function on the endpoint /user/Jake will return the response as Hello Jake.
Environment Variables
Users can access environment variables inside the cloud functions.
Environment variables can be added by going to the corresponding environment’s Settings page on Launch.
Example:
export default async function handler(req, res) {
const uri = process.env.DATABASE_URI;
const client = new DBClient(uri);
// perform database operations...
res.status(200).send("Success");
}
Note: A new deployment must be triggered after adding/modifying environment variables.
Debugging Cloud Functions
Server Logs
The Server Logs section displays real-time logs generated by the cloud functions from the latest deployment.
Note: For both Live and Archived statuses, server logs are retained for 24 hours, with a maximum of 5000 most recent logs viewable. We recommend using Log Targets to forward server logs to your logging platform in real-time for future reference.
Deployment Logs
Launch throws a Cloud functions deployment error when it is unable to deploy your code to Launch Cloud Function. This can happen in the following scenario:
- Bundling failed: Bundling your Launch Cloud Function failed due to a syntax error in your code or missing dependencies in package.json which are used by the Cloud Function(s).
Deploying a Project with Only Launch Cloud Functions
If you want to deploy a project that does not have a website but only Launch Cloud Functions, you can do so by following the steps given below:
- Ensure the root directory has a /functions folder as mentioned above.
- While setting up the project, set the Framework Preset to Other.
- If the Cloud Functions have dependency packages, follow the steps below:
- Ensure that a package.json file is present at the root directory.
- Set Build Command to npm install to install the dependency packages.
Running Cloud Functions Locally
You can run your Launch project Cloud Functions locally using the launch:functions command in CLI.
Limitations
- Writing Cloud Functions using TypeScript is currently not supported.
- Currently, running a standalone server (for example, Express, Fastify, and so on) in a Launch Cloud Function is not supported.