Skip to content

Cosmic Functions

Cosmic and AWS Logos

How it works

You can deploy Node.js functions to AWS through your Bucket Dashboard located at Your Bucket > Settings > Functions. AWS Lambda functions are infinitely scalable, highly cost effective (AWS gives you 1M requests per month free), and you never have to pay for idle server time. You can have unlimited Functions in your Cosmic Bucket and the feature is 100% free to use.

What's required?

  1. Your AWS access key and secret key. (See instructions below)
  2. Node.js codebase (zip or link to git repo) that follows Lambda requirements.

How to get your AWS access keys

Follow these steps to get your AWS access keys:

  1. Create or login to your Amazon Web Services Account and go to the Identity & Access Management (IAM) page.

  2. Click on Users and then Add user. Enter a name in the first field to remind you this User is from Cosmic, like cosmic-admin. Enable Programmatic access by clicking the checkbox. Click Next to go through to the Permissions page.

  3. Click on Attach existing policies directly. Search for and select AdministratorAccess then click through to Next: Review. Check everything looks good and click Create user.

  4. View and copy the API Key & Secret to a temporary place. You'll need it for all of your Cosmic Function deploys.

Required Files

Entry file

The index.js file of your codebase will need to export a handler function and follow the format for AWS Lambda Node.js function handling. The version of Node.js deployed is v10.x. Here's a simple Hello World example:

// index.js
module.exports.handler = function (event, context, callback) {
const response = {
statusCode: 200,
headers: {
'Access-Control-Allow-Origin': '*' // Required for CORS support to work
body: 'Hello World ' + process.env.SOME_OPTIONAL_VAR
callback(null, response)

Function config file

The function.json file includes information that Cosmic uses to deploy your function. Here's an example:

"title": "Hello World",
"description": "Says Hello World and some custom message from env var.",
"image_url": "",
"stage": "staging",
"env_vars": [
"value": ""
"routes": [
"path": "hello-world",
"method": "get",
"cors": true

function.json Properties

titleStringFunction title
descriptionStringFunction description (HTML allowed)
image_urlStringImage thumbnail URL
stageStringdefaults to dev
repo_urlStringFunction git repo url
env_varsArraykey / value for environment variables
routesArrayFunction routes: properties include path (string), method (string) and cors (bool)
dynamic_routesBoolAllows dynamic routes to your function. Overrides the routes property.

Dynamic Routes

Your Function can serve dynamic routes, like an Express application (see the Serverless Starter). To make routes dynamic, add the dynamic_routes property set to true in your function.json file:

"title": "Dynamic Routes",
"description": "A serverless function with dynamic routes.",
"image_url": "",
"stage": "dev",
"dynamic_routes": true

Your index.js file will look something like this:

// index.js
const serverless = require('serverless-http')
const express = require('express')
const app = express()
app.get('/:slug?', (req, res) => {
res.json({ message: 'Your dynamic slug is ' + req.params.slug })
module.exports.handler = serverless(app)

Install your Function

Go to Your Bucket > Settings > Functions to deploy a new Function. Whether you install from git repo URL or .zip file, make sure to include both index.js and function.json files in your codebase.

Deploy your Function

After your Function is installed, follow these steps:

  1. Go to Your Bucket > Settings > Functions > Your Function.
  2. Add your AWS credentials.
  3. Add any other required environment variables.
  4. Click "Deploy Function".


View these Function examples on GitHub:

We hope you enjoy the new freedom you have to deploy serverless functions using Cosmic JS. If you have any questions, you can reach out to us on Twitter and join the community on Slack.