aws-simple
Advanced tools
A Node.js interface for AWS that allows easy configuration and deployment of simple web apps.
A Node.js interface for AWS that allows easy configuration and deployment of simple web apps.
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.
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 not supported.
I deliberately kept it simple. An app with a more complex setup should be set up manually with the AWS CDK/SDK.
You need to install aws-simple and aws-cdk as dependencies, e.g. with:
yarn add --dev aws-simple aws-cdk
You need to create an AWS IAM user with programmatic access and the following attached policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:*",
"cloudformation:*",
"iam:*",
"lambda:*",
"route53:*",
"s3:*"
],
"Resource": "*"
}
]
}
Note: This policy has more rights than necessary and should be more specific for security.
You can install the aws CLI, e.g. with:
brew install awscli
You can then set up the AWS profile using the credentials from the AWS IAM user you just created:
aws configure
AWS Access Key ID [None]: ********************
AWS Secret Access Key [None]: ****************************************
Default region name [None]: eu-central-1
Default output format [None]: json
Note: If a profile other than the default profile is to be set up, the aws
CLI can be called with the --profile CLI option, e.g.:
aws configure --profile my-profile
As an alternative to using the aws CLI, you can create the following files
manually:
cat ~/.aws/credentials
[default]
aws_access_key_id = ********************
aws_secret_access_key = ****************************************
cat ~/.aws/config
[default]
output = json
region = eu-central-1
The following two environment variables AWS_PROFILE and AWS_DEFAULT_PROFILE
are evaluated in the specified order. If neither of the two environment
variables is set, the default profile is used.
The following is an example of setting a specific profile:
AWS_PROFILE=my-profile yarn aws-simple list
The following two environment variables AWS_ACCESS_KEY_ID and
AWS_SECRET_ACCESS_KEY are evaluated. If these are not set, an attempt is made
to read the credentials from the AWS shared credentials file using the AWS
profile. The default location of the file (~/.aws/credentials) can be
overwritten by setting the environment variable AWS_SHARED_CREDENTIALS_FILE.
The following two environment variables AWS_REGION and AWS_DEFAULT_REGION
are evaluated in the specified order. If neither of the two environment
variables is set, an attempt is made to read the region from the AWS config file
using the AWS profile. The default location of the file (~/.aws/config) can be
overwritten by setting the environment variable AWS_CONFIG_FILE.
To use the aws-simple CLI you have to create a top-level config file named
aws-simple.config.js which exports an object compatible to the
AppConfig interface.
For example, a config file with the following content describes a simple app consisting of a single static HTML file:
exports.default = {
appName: 'my-app',
appVersion: 'latest',
createStackConfig: (port) => ({
s3Configs: [
{
type: 'file',
publicPath: '/',
localPath: 'dist/index.html',
bucketPath: 'index.html',
},
],
}),
};
Note: The createStackConfig function optionally gets a port argument. It is
set when the function is called in the context of the
aws-simple start [options] CLI command. This gives the opportunity to create
different
StackConfig objects
for either AWS or the local DEV environment.
The createStackConfig function is only called in the context of the following
CLI commands:
aws-simple create [options]aws-simple upload [options]aws-simple start [options]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 app:
yarn cdk bootstrap --app 'yarn aws-simple create'
Note: This command only needs to be executed once.
yarn aws-simple start
Note: When changing the aws-simple config file, the DEV server must be
restarted. If a bundler such as Parcel or Webpack is used, its watcher must be
started in addition to the DEV server.
Create and deploy a stack using the CDK:
yarn cdk deploy --app 'yarn aws-simple create'
The name of the deployed stack consists of the app name (e.g. my-app) in
combination with the app version (e.g. latest) such as
aws-simple--my-app--latest.
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
Example package.json scripts:
{
"scripts": {
"deploy": "cdk deploy --app 'yarn aws-simple create'",
"postdeploy": "aws-simple upload"
}
}
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.
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: 'my-app',
appVersion: 'latest',
createStackConfig: () => ({
/* ... */
}),
};
In order to use a custom domain, a public certificate and a public hosted zone must be created manually. You can then configure a custom domain as follows:
const appName = 'my-app';
const appVersion = process.env.APP_VERSION || 'latest';
exports.default = {
appName,
appVersion,
createStackConfig: () => ({
customDomainConfig: {
certificateArn:
'arn:aws:acm:eu-central-1:************:certificate/********-****-****-****-************',
hostedZoneId: '**************',
hostedZoneName: 'example.com',
aliasRecordName: appVersion !== 'latest' ? appVersion : undefined,
},
}),
};
Note: Different app versions allow multiple stacks of the same app to be
deployed simultaneously. In this case the optional aliasRecordName property is
used to give each stack its own URL, for example example.com or
beta.example.com (APP_VERSION=beta).
You can configure a Lambda function that can be accessed via GET request at the
URL my-app.example.com/endpoint as follows:
const appVersion = process.env.APP_VERSION || 'latest';
exports.default = {
appName: 'my-app',
appVersion,
createStackConfig: (port) => ({
lambdaConfigs: [
{
httpMethod: 'GET',
publicPath: '/endpoint',
localPath: 'path/to/lambda.js',
// Optional example properties
description: 'My Lambda function.',
memorySize: 3008,
timeoutInSeconds: 28,
loggingLevel: 'INFO',
cachingEnabled: true,
cacheTtlInSeconds: 3600,
acceptedParameters: {
foo: {},
bar: {isCacheKey: true},
baz: {required: true},
qux: {isCacheKey: true, required: true},
},
environment: {
BASE_URL: port
? `http://localhost:${port}` // Local DEV server
: `https://${appVersion}.example.com`,
},
},
],
}),
};
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 = {
appName: 'my-app',
appVersion: 'latest',
createStackConfig: () => ({
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.
You can configure an S3 file that can be accessed via GET request at the URL
my-app.example.com/ as follows:
exports.default = {
appName: 'my-app',
appVersion: 'latest',
createStackConfig: () => ({
s3Configs: [
{
type: 'file',
publicPath: '/',
localPath: 'path/to/file.html',
// Optional example properties
bucketPath: 'file.html',
cachingEnabled: true,
cacheTtlInSeconds: 3600,
},
],
}),
};
Note: The file specified under the localPath is loaded into the S3 bucket
associated with the stack using the aws-simple upload [options] CLI command.
The optionally specified bucketPath or, if not specified, the publicPath is
used as the S3 object key.
You can configure an S3 folder whose contained files can be accessed via GET
request at the URL my-app.example.com/assets/* as follows:
exports.default = {
appName: 'my-app',
appVersion: 'latest',
createStackConfig: () => ({
s3Configs: [
{
type: 'folder',
publicPath: '/assets',
localPath: 'path/to/folder',
// Optional example properties
responseHeaders: {
cacheControl: 'max-age=157680000',
},
cachingEnabled: true,
cacheTtlInSeconds: 3600,
},
],
}),
};
Note: All files contained in the folder specified under the localPath 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 object must be created for each nested folder.
Since the config file is a node module, individual properties can also be set
dynamically. For example, you can set the appVersion based on the current Git
commit SHA or Git tag ref:
const {isTagDirty, short, tag} = require('git-rev-sync');
function detectAppVersion() {
const {GITHUB_REF, GITHUB_SHA} = process.env;
if (GITHUB_REF) {
return GITHUB_REF.replace(/\./g, '-');
}
if (GITHUB_SHA) {
return GITHUB_SHA.slice(7);
}
if (isTagDirty()) {
return short();
}
return tag().replace(/\./g, '-');
}
const appVersion = detectAppVersion();
exports.default = {
appName: 'my-app',
appVersion,
createStackConfig: () => ({
customDomainConfig: {
/* ... */
hostedZoneName: 'example.com',
aliasRecordName: appVersion,
},
}),
};
You can specify media types (e.g. image/png, application/octet-stream, etc.)
to be treated as binary as follows:
exports.default = {
appName: 'my-app',
appVersion: 'latest',
createStackConfig: () => ({
binaryMediaTypes: ['font/woff2'],
}),
};
You can enable compression for an API as follows:
exports.default = {
appName: 'my-app',
appVersion: 'latest',
createStackConfig: () => ({
minimumCompressionSizeInBytes: 1000,
}),
};
Basic CORS support can be enabled as follows:
exports.default = {
appName: 'my-app',
appVersion: 'latest',
createStackConfig: () => ({
enableCors: true,
}),
};
Note: Additionally, Lambda handlers must explicitly set any required CORS
headers like Access-Control-Allow-Origin on their response.
You can configure basic authentication for an API, and require authentication for certain API methods, as follows:
exports.default = {
appName: 'my-app',
appVersion: 'latest',
createStackConfig: () => ({
basicAuthenticationConfig: {
username: process.env.USERNAME,
password: process.env.PASSWORD,
cacheTtlInSeconds: 300,
},
lambdaConfigs: [
{
httpMethod: 'GET',
publicPath: '/secret-endpoint',
localPath: 'path/to/secret-lambda.js',
authenticationRequired: true,
},
{
httpMethod: 'GET',
publicPath: '/public-endpoint',
localPath: 'path/to/public-lambda.js',
},
],
s3Configs: [
{
type: 'file',
publicPath: '/secret-file',
localPath: 'path/to/secret-file.html',
authenticationRequired: true,
},
{
type: 'file',
publicPath: '/public-file',
localPath: 'path/to/public-file.html',
},
],
}),
};
Note: Basic authentication is not handled by the local DEV server.
It can be useful to deliver the same single-page Application under different
paths. Instead of specifying multiple s3Configs or lambdaConfigs, you can
also specify a catch-all s3Config or lambdaConfig. For example a single
greedy publicPath (e.g. publicPath: '/{proxy+}') will match requests made to
/foo, /bar, and /baz/qux, but to match also / it needs a non-greedy
publicPath (publicPath: '/') in addition.
exports.default = {
appName: 'my-app',
appVersion: 'latest',
createStackConfig: () => ({
s3Configs: [
{
type: 'file',
publicPath: '/',
localPath: 'dist/index.html',
bucketPath: 'index.html',
},
{
type: 'file',
publicPath: '/{proxy+}',
localPath: 'dist/index.html',
bucketPath: 'index.html',
},
],
}),
};
exports.default = {
appName: 'my-app',
appVersion: 'latest',
createStackConfig: () => ({
lambdaConfigs: [
{
httpMethod: 'GET',
publicPath: '/',
localPath: 'path/to/lambda.js',
},
{
httpMethod: 'GET',
publicPath: '/{proxy+}',
localPath: 'path/to/lambda.js',
},
],
}),
};
Some changes
to an existing stack require a redeployment of the API Gateway. So if changes to
a stack do not work, the aws-simple redeploy command might help.
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 a 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
aws-simple redeploy [options] Redeploy the API Gateway
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.
aws-simple create [options]
Create a stack using the CDK
Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
Examples:
npx aws-simple create
npx cdk deploy --app 'npx aws-simple create'
aws-simple upload [options]
Upload files to S3
Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
Examples:
npx aws-simple upload
aws-simple start [options]
Start a local DEV server
Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
--port The port to listen on if available, otherwise listen on a random
port [number] [default: 3000]
--cache Enable caching of successful caching-enabled Lambda function
results per request URL [boolean] [default: false]
--verbose Enable logging of successful Lambda function results
[boolean] [default: false]
Examples:
npx aws-simple start
npx aws-simple start --port 3001 --cache --verbose
aws-simple list [options]
List all deployed stacks
Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
Examples:
npx aws-simple list
aws-simple tag [options]
Tag a deployed stack
Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
--add The tags to add [array] [default: []]
--remove The tags to remove [array] [default: []]
--yes The confirmation message will automatically be answered with yes
[boolean] [default: false]
Examples:
npx aws-simple tag --add latest release --remove prerelease
npx aws-simple tag --add prerelease --yes
aws-simple clean-up [options]
Clean up old deployed stacks
Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
--min-age The minimum age (in days) of a stack for deletion
[number] [default: 30]
--exclude Tags that exclude a stack from deletion [array] [default: []]
--yes The confirmation message will automatically be answered with yes
[boolean] [default: false]
Examples:
npx aws-simple clean-up
npx aws-simple clean-up --min-age 14 --exclude release prerelease --yes
aws-simple redeploy [options]
Redeploy the API Gateway
Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
Examples:
npx aws-simple redeploy
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.
FAQs
Production-ready AWS website deployment with minimal configuration.
The npm package aws-simple receives a total of 792 weekly downloads. As such, aws-simple popularity was classified as not popular.
We found that aws-simple demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
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.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.