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});

}

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.

Additional helpers are provided inside the Request and Response objects passed to the function. These are:

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:

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' });

}

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

  }

}

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.

The memory size for a Launch Cloud Function is 1024 MB.

The Launch Cloud Functions runtime environment leverages Node.js to power its execution environment.

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.

Launch Cloud Functions support the x86_64 instruction set.

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.params object.

Example: functions/user/[name].js

Here, the value passed for the path segment is made available to the req.params object under the key used for the filename(name).

// functions/user/[name].js


export default function handler(request, response) {

  response.send(`Hello ${request.params.name}!`);

}

Running the function on the endpoint /user/Jake will return the response as Hello Jake.

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.

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.

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).

When deploying projects on Contentstack Launch that utilize server-side frameworks, it is recommended to use the native server-side capabilities offered by the framework itself. This leverages the native functionality provided by each framework and avoids conflicts with Launch Cloud Functions.

For example:

• Next.js Pages Router: Use API routes
• Next.js App Router: Use Route Handlers
• Gatsby: Use Gatsby Functions
• Other: Use other framework with server command

If a project with server-side functionality is detected, Launch Cloud Functions will be automatically disabled during deployment. This will be reflected in the Deployment Logs with the following message:

Cloud functions:

Disabled with server side deployment

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.

You can run your Launch project Cloud Functions locally using the launch:functions command in CLI.

• 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.