# 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 (opens new window)), 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?

Your AWS access key and secret key. (See instructions below)
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:

Create or login (opens new window) to your Amazon Web Services Account and go to the Identity & Access Management (IAM) page.
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.
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.
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 (opens new window). 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": "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:

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

# Examples

View these Function examples on GitHub:

Function Starter (opens new window)
- Get started with Cosmic Functions.
SendGrid Email (opens new window)
- Send an email using SendGrid.
Stripe Charge (opens new window)
- 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 (opens new window) and join the community on Slack (opens new window).

← CLI