Docs

# Cosmic JS Functions

Cosmic JS 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 JS 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 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:

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.

← Webhooks →