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.
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.
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.
Install aws-simple as development dependency, e.g. with:
yarn add --dev aws-simple
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.
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 top-level config file called aws-simple.config.js.
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'
}
]
};
// @ts-check
/**
* @type {import('aws-simple').AppConfig}
*/
exports.default = {
appName: 'myapp',
defaultStackName: 'mystack',
region: 'eu-central-1'
};
Note: The AppConfig interface can be viewed here.
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.
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
Note: Different stack names allow multiple stacks of the same app to be
deployed simultaneously. For example, the getAliasRecordName function in the
customDomainConfig can be used to give each stack its own URL.
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.
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.
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.
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
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
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 results per request URL
[boolean] [default: false]
--verbose Enable logging of successful Lambda results
[boolean] [default: false]
Examples:
aws-simple start
aws-simple start --port 1985 --cached
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
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
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
npm version 1.0.0 && git push --follow-tags
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.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.
Security News
Research
Socket researchers found a malicious Maven package impersonating the legitimate ‘XZ for Java’ library, introducing a backdoor for remote code execution.