Cosmic Functions Deploy code without having to manage infrastructure.

What are Cosmic Functions?

With Cosmic Functions (currently in public Beta), you can deploy server-side code without having to manage server infrastructure. Simply connect your AWS account and deploy code from the comfort of your Cosmic JS Bucket.

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 JS Bucket and the feature is 100% free to use.

What's required?

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

Make sure your codebase includes the following 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 v8.10 which means you can use the async / await pattern. 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 JS 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": "https://cosmic-s3.imgix.net/ed58d700-7b2c-11e8-9d6b-252d8b978aea-SendGrid-Logo.png",
  "stage": "staging",
  "env_vars": [
    {
      "key": "SOME_OPTIONAL_VAR",
      "value": ""
    }
  ],
  "routes": [
    {
      "path": "hello-world",
      "method": "get",
      "cors": true
    }
  ]
}

function.json Properties

Key Type Description
title String Function title
description String Function description (HTML allowed)
image_url String Image thumbnail URL
stage String defaults to dev
repo_url String Function git repo url
env_vars Array key / value for environment variables
routes Array Function routes: properties include path (string), method (string) and cors (bool)
dynamic_routes Bool Allows 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": "https://cosmicjs.com/images/logos/serverless.svg",
  "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".

Examples

View these Function examples on GitHub:

Function Starter

Get started with Cosmic Functions.

SendGrid Email

Send an email using SendGrid.

Stripe Charge

Submit a charge to Stripe.

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.