Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

aws-simple

Package Overview
Dependencies
Maintainers
1
Versions
123
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

aws-simple

A Node.js interface for AWS that allows easy configuration and deployment of simple web apps.

  • 0.0.12
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
1.1K
decreased by-13.44%
Maintainers
1
Weekly downloads
 
Created
Source

aws-simple

A Node.js interface for AWS that allows easy configuration and deployment of simple web apps.

Contents

  • Quick Overview
  • Motivation
  • Getting Started
  • CLI Usage
  • Development

Quick Overview

aws-simple allows you to easily create and deploy an API Gateway with a custom domain and optional alias record, host static web resources via S3, and provision public backend APIs via Lambda. In addition, a local DEV server can be started to emulate the resulting AWS infrastructure.

aws-simple-example

For a quick impression, an example app is available that consists essentially of a React component that retrieves text from a Lambda function using a React.useEffect hook and displays it. Parcel is used for bundling and TypeScript as language.

Motivation

In my job I mainly build web apps on top of existing backend/CMS systems. Since many of the frontend tech stacks are similar again and again, I created an abstraction for the AWS CDK/SDK for a faster and easier setup.

Since existing backend/CMS systems are used, an additional persistence layer is rarely required. Therefore, setting up such a layer (e.g. with Amazon DynamoDB) is currently not supported.

I deliberately kept it simple. An app with a more complex setup should be set up manually with the AWS CDK/SDK.

Getting Started

Install

Install aws-simple and aws-cdk as development dependencies, e.g. with:

yarn add --dev aws-simple aws-cdk

Create An AWS IAM User

Create an AWS IAM user with programmatic access and the following attached policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["cloudformation:*", "apigateway:*", "s3:*"],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": ["lambda:*"],
      "Resource": "arn:aws:lambda:*:*:function:myapp-*"
    },
    {
      "Effect": "Allow",
      "Action": ["iam:*"],
      "Resource": "arn:aws:iam::*:role/myapp-*"
    },
    {
      "Effect": "Allow",
      "Action": ["iam:CreateServiceLinkedRole"],
      "Resource": "arn:aws:iam::*:role/aws-service-role/ops.apigateway.amazonaws.com/*"
    },
    {
      "Effect": "Allow",
      "Action": ["route53:*"],
      "Resource": "arn:aws:route53:::*"
    }
  ]
}

Note: Please replace the app name (myapp) with your own. All resources created with CloudFormation have the app name combined with the stack name as a prefix for their ID such as myapp-mystack-resource-s3-bucket.

Create An AWS CLI Profile

Install the aws CLI, e.g. with:

brew install awscli

Then set up the AWS CLI profile using the access key from the AWS IAM user you just created:

aws configure --profile clebert
AWS Access Key ID [None]: ********************
AWS Secret Access Key [None]: ****************************************
Default region name [None]: eu-central-1
Default output format [None]: json

As an alternative to using the aws CLI, the following files can also be created manually:

cat ~/.aws/credentials
[clebert]
aws_access_key_id = ********************
aws_secret_access_key = ****************************************
cat ~/.aws/config
[profile clebert]
output = json
region = eu-central-1

Note: Please replace the profile (clebert) and also the region (eu-central-1) if necessary.

Create A Config File

To use the aws-simple CLI you have to create a top-level node module config file named aws-simple.config.js which exports an object compatible to the AppConfig interface.

For example, the following app config describes a simple app consisting of a single static HTML file:

exports.default = {
  appName: 'myapp',
  defaultStackName: 'mystack',
  region: 'eu-central-1',
  s3Configs: [
    {
      type: 'file',
      publicPath: '/',
      localPath: 'dist/app/index.html',
      bucketPath: 'index.html'
    }
  ]
};

Note: Different stack names allow multiple stacks of the same app to be deployed simultaneously. The specified default stack name can be overwritten with most aws-simple <command> [options] CLI commands using the --stack-name CLI option.

Use TypeScript For Auto-Completion Support

TypeScript 2.3 and later support type-checking in *.js files by adding a // @ts-check comment to them:

// @ts-check

/**
 * @type {import('aws-simple').AppConfig}
 */
exports.default = {
  appName: 'myapp',
  defaultStackName: 'mystack',
  region: 'eu-central-1'
};
Example Configuration Of A Custom Domain

In order to use a custom domain, a certificate and a hosted zone must be created manually. You can then configure the custom domain as follows:

exports.default = {
  /* ... */
  customDomainConfig: {
    certificateArn:
      'arn:aws:acm:eu-central-1:************:certificate/********-****-****-****-************',
    hostedZoneId: '**************',
    hostedZoneName: 'example.com',
    getAliasRecordName: stackName => stackName
  }
};

Note: Different stack names allow multiple stacks of the same app to be deployed simultaneously. In this case the optional getAliasRecordName function is used to give each stack its own URL, for example mystack.example.com.

Example Configuration Of A Lambda Function

You can configure a Lambda function that can be accessed via GET request at the URL mystack.example.com/endpoint as follows:

exports.default = {
  /* ... */
  lambdaConfigs: [
    {
      httpMethod: 'GET',
      publicPath: '/endpoint',
      localPath: 'path/to/lambda.js',
      memorySize: 3008,
      timeoutInSeconds: 30,
      environment: {KEY: 'value'},
      cachingEnabled: true,
      cacheTtlInSeconds: 600,
      acceptedParameters: {
        foo: {},
        bar: {isCacheKey: true},
        baz: {required: true},
        qux: {isCacheKey: true, required: true}
      }
    }
  ]
};

The contents of file path/to/lambda.js could look like this:

async function handler() {
  return {
    statusCode: 200,
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify('Hello, World!')
  };
}

exports.handler = handler;

If the export of the Lambda function node module has a different name than handler, this must be explicitly specified in the Lambda configuration:

exports.default = {
  /* ... */
  lambdaConfigs: [
    {
      /* ... */
      handler: 'myHandler'
    }
  ]
};

Note: If external node modules are to be referenced in the Lambda function node module, it must be bundled with a bundler such as Webpack (in this case you have to set the target to node: {target: 'node'}) to create a single node module bundle.

Example Configuration Of An S3 File

You can configure an S3 file that can be accessed via GET request at the URL mystack.example.com/ as follows:

exports.default = {
  /* ... */
  s3Configs: [
    {
      type: 'file',
      publicPath: '/',
      localPath: 'path/to/file.html',
      bucketPath: 'file.html'
    }
  ]
};

Note: The file specified under the local path is loaded into the S3 bucket associated with the stack using the aws-simple upload [options] CLI command. The optionally specified bucket path or, if not specified, the public path is used as the S3 object key.

Example Configuration Of An S3 Folder

You can configure an S3 folder whose contained files can be accessed via GET request at the URL mystack.example.com/assets/* as follows:

exports.default = {
  /* ... */
  s3Configs: [
    {
      type: 'folder',
      publicPath: '/assets',
      localPath: 'path/to/folder',
      responseHeaders: {
        accessControlAllowOrigin: '*',
        cacheControl: 'max-age=157680000'
      }
    }
  ]
};

Note: All files contained in the folder specified under the local path are loaded into the S3 bucket associated with the stack using the aws-simple upload [options] command. Nested folders are ignored! Thus a separate S3 Config must be created for each nested folder.

Dynamic Setting Of Config Properties

Since the config file is a node module, individual properties can also be set dynamically. An example would be to set the AWS region by reading an ENV variable:

exports.default = {
  /* ... */
  region: process.env.AWS_DEFAULT_REGION || 'eu-central-1'
};

Another example is to set the default stack name based on the current hash or tag:

const {isTagDirty, short, tag} = require('git-rev-sync');

exports.default = {
  /* ... */
  defaultStackName: isTagDirty()
    ? short(undefined, 8)
    : tag().replace(/\./g, '-')
};
Enable Binary Support

You can specify media types (e.g. image/png, application/octet-stream, etc.) to be treated as binary as follows:

exports.default = {
  /* ... */
  binaryMediaTypes: ['font/woff2']
};
Enable Payload Compression

You can enable compression for an API as follows:

exports.default = {
  /* ... */
  minimumCompressionSizeInBytes: 1000
};

Bootstrap Your AWS Environment

Before you can use the AWS CDK you must bootstrap your AWS environment to create the infrastructure that the AWS CDK CLI needs to deploy your AWS CDK app:

yarn cdk bootstrap --app 'yarn aws-simple create' --profile clebert

Note: This command only needs to be executed once. For more information see here.

Deploy A Stack To AWS

Create a stack using the CDK:

yarn cdk deploy --app 'yarn aws-simple create' --profile clebert

Caution: Re-deploying an already deployed stack (so a stack with the same name) will remove all tags set with aws-simple tag [options].

Upload files to S3:

yarn aws-simple upload --profile clebert
package.json Scripts Example
{
  "scripts": {
    "deploy": "cdk deploy --app 'yarn aws-simple create' --profile clebert",
    "postdeploy": "aws-simple upload --profile clebert"
  }
}

Note: In a CI pipeline the deploy script should be called with the additional argument --require-approval never, e.g. yarn deploy --require-approval never.

Start A Local DEV Server

yarn aws-simple start --port 1985 --cached

Note: If a bundler such as Parcel or Webpack is used, its watcher must be started in addition to the DEV server.

When changing the aws-simple config file, the DEV server must be restarted.

CLI Usage

Usage: aws-simple <command> [options]

Commands:
  aws-simple create [options]    Create a stack using the CDK
  aws-simple upload [options]    Upload files to S3
  aws-simple start [options]     Start local DEV server
  aws-simple list [options]      List all deployed stacks
  aws-simple tag [options]       Tag a deployed stack
  aws-simple clean-up [options]  Clean up old deployed stacks

Options:
  --version   Show version number                                      [boolean]
  -h, --help  Show help                                                [boolean]

A Node.js interface for AWS that allows easy configuration and deployment of
simple web apps.

Create A Stack Using The CDK

aws-simple create [options]

Create a stack using the CDK

Options:
  --version     Show version number                                    [boolean]
  -h, --help    Show help                                              [boolean]
  --config      The path to the config file
                                      [string] [default: "aws-simple.config.js"]
  --stack-name  The stack name to be used instead of the default one declared in
                the config file                                         [string]

Examples:
  cdk deploy --app 'aws-simple create' --profile clebert
  cdk deploy --app 'aws-simple create --stack-name stage' --profile clebert

Upload Files To S3

aws-simple upload [options]

Upload files to S3

Options:
  --version     Show version number                                    [boolean]
  -h, --help    Show help                                              [boolean]
  --config      The path to the config file
                                      [string] [default: "aws-simple.config.js"]
  --profile     The AWS profile name as set in the shared credentials file
                                                             [string] [required]
  --stack-name  The stack name to be used instead of the default one declared in
                the config file                                         [string]

Examples:
  aws-simple upload --profile clebert
  aws-simple upload --profile clebert --stack-name stage

Start Local DEV Server

aws-simple start [options]

Start local DEV server

Options:
  --version   Show version number                                      [boolean]
  -h, --help  Show help                                                [boolean]
  --config    The path to the config file
                                      [string] [default: "aws-simple.config.js"]
  --port      The port to listen on                     [number] [default: 3000]
  --cached    Enable caching of successful Lambda function results per request
              URL                                     [boolean] [default: false]
  --verbose   Enable logging of successful Lambda function results
                                                      [boolean] [default: false]

Examples:
  aws-simple start
  aws-simple start --port 1985 --cached

List All Deployed Stacks

aws-simple list [options]

List all deployed stacks

Options:
  --version   Show version number                                      [boolean]
  -h, --help  Show help                                                [boolean]
  --config    The path to the config file
                                      [string] [default: "aws-simple.config.js"]
  --profile   The AWS profile name as set in the shared credentials file
                                                             [string] [required]

Examples:
  aws-simple list --profile clebert

Tag A Deployed Stack

aws-simple tag [options]

Tag a deployed stack

Options:
  --version     Show version number                                    [boolean]
  -h, --help    Show help                                              [boolean]
  --config      The path to the config file
                                      [string] [default: "aws-simple.config.js"]
  --profile     The AWS profile name as set in the shared credentials file
                                                             [string] [required]
  --tag-name    The tag name                                 [string] [required]
  --stack-name  The stack name to be used instead of the default one declared in
                the config file                                         [string]

Examples:
  aws-simple tag --profile clebert --tag-name released
  aws-simple tag --profile clebert --tag-name released --stack-name stage

Clean Up Old Deployed Stacks

aws-simple clean-up [options]

Clean up old deployed stacks

Options:
  --version   Show version number                                      [boolean]
  -h, --help  Show help                                                [boolean]
  --config    The path to the config file
                                      [string] [default: "aws-simple.config.js"]
  --profile   The AWS profile name as set in the shared credentials file
                                                             [string] [required]
  --max-age   The maximum age (in days) of a stack, all older stacks will be
              deleted                                     [number] [default: 30]
  --preserve  Optional tag names that prevent a stack from being deleted
              regardless of its age                                      [array]
  --yes       The confirmation message will automatically be answered with Yes
                                                      [boolean] [default: false]

Examples:
  aws-simple clean-up --profile clebert
  aws-simple clean-up --profile clebert --max-age 14 --preserve released
  aws-simple clean-up --profile clebert --preserve released protected

Development

Publish A New Release

yarn release patch
yarn release minor
yarn release major

After a new release has been created by pushing the tag, it must be published via the GitHub UI. This triggers the final publication to npm.


Copyright (c) 2019, Clemens Akens. Released under the terms of the MIT License.

Keywords

FAQs

Package last updated on 10 Oct 2019

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc