AWS Static Deploy CLI

CLI for deploying static websites to AWS S3 and CloudFront with versioning and promotion workflow.

This tool facilitates a robust deployment strategy by uploading versioned assets to S3 and using CloudFront KeyValueStore to point different environments (like staging and latest) to specific versions.

Features

• Uploads build assets to S3 under a versioned path.
• Supports semantic versioning, with easy bumping for patch, minor, and major releases.
• Uses CloudFront KeyValueStore to manage environment-to-version mapping.
• Simple promote command to move a version from staging to latest.
• Supports Gzip and Brotli compression for specified file types.
• Progress indicators for asset compression.

Installation

npm install -g @mypolis.eu/aws-static-deploy

Or use it with npx:

npx @mypolis.eu/aws-static-deploy <command>

Configuration

The CLI requires a deploy.config.json file in the root of your project.

{
	"project": {
		"name": "my-awesome-project"
	},
	"aws": {
		"profile": "your-aws-profile",
		"region": "eu-west-1",
		"s3BucketName": "my-static-assets-bucket",
		"kvsArn": "arn:aws:cloudfront::123456789012:key-value-store/your-kvs-id"
	},
	"build": {
		"root": "dist",
		"compression": {
			"files": ["Build/**/*"],
			"gzipLevel": 9,
			"brotliQuality": 5
		},
		"cacheRules": [
			{
				"files": "index.html",
				"cacheControl": "no-cache"
			},
			{
				"files": "Build/**/*",
				"cacheControl": "max-age=31536000, public, immutable"
			},
			{
				"files": "StreamingAssets/**/*",
				"cacheControl": "max-age=31536000, public, immutable"
			},
			{
				"files": "TemplateData/**/*",
				"cacheControl": "max-age=31536000, public, immutable"
			}
		]
	}
}

Configuration Fields

• project.name: A unique name for your project. This is used as a prefix for S3 paths and KeyValueStore keys.
• aws.profile: The AWS credentials profile to use (from ~/.aws/credentials).
• aws.region: The AWS region for S3 and CloudFront KeyValueStore.
• aws.s3BucketName: The name of the S3 bucket to deploy assets to.
• aws.kvsArn: The ARN of the CloudFront KeyValueStore used for version mapping.
• build.root: The path to the directory containing your built static assets.
• build.compression.files: An array of micromatch glob patterns for files that should be compressed with Gzip and Brotli.
• build.compression.gzipLevel (optional): The compression level for Gzip (1-9). Defaults to 9.
• build.compression.brotliQuality (optional): The quality for Brotli compression (0-11). Defaults to 5.
• build.cacheRules (optional): An array of objects defining caching rules. Each object must have:
  • files: A micromatch glob pattern for files to apply the rule to.
  • cacheControl: The Cache-Control header value to set for matching files. If not provided, a default set of rules will be applied: index.html will be no-cache, and common assets (.js, .css, .ico, .png, etc.) will be max-age=31536000, public, immutable.

AWS Prerequisites

1. S3 Bucket: An S3 bucket to store the versioned static assets.
2. CloudFront Distribution: A CloudFront distribution configured to serve content from the S3 bucket.
3. CloudFront KeyValueStore: A KeyValueStore associated with your CloudFront distribution. This is used to map environments to versions.
4. CloudFront Function: A CloudFront Function that reads from the KeyValueStore to determine which version of an asset to serve.
5. IAM Permissions: The AWS user/role associated with the profile must have permissions for S3 (List, PutObject) and CloudFront KeyValueStore (Describe, Get, Update).

Usage

The CLI is available under the aws-static-deploy command.

publish [versionNumber]

Uploads a new version to S3 and sets it as the staging version in the KeyValueStore.

If [versionNumber] is not provided, it will automatically bump the latest version found in S3. The default bump is patch.

Options:

• --patch, -p: Bumps the patch version (e.g., 1.0.0 -> 1.0.1).
• --minor, -m: Bumps the minor version (e.g., 1.0.0 -> 1.1.0).
• --major, -M: Bumps the major version (e.g., 1.0.0 -> 2.0.0).

Examples:

# Publish a new patch version (e.g., if latest is 1.2.3, this creates 1.2.4)
aws-static-deploy publish

# Publish a new minor version
aws-static-deploy publish --minor

# Publish a specific version
aws-static-deploy publish 2.0.0

promote

Promotes the version currently in staging to latest. This is done by updating the latest key in the KeyValueStore to point to the same version as the staging key.

aws-static-deploy promote

set-version <environment> <versionNumber>

Manually sets an environment to a specific, existing version.

Arguments:

• environment: The environment to update (e.g., staging, latest).
• versionNumber: The existing version number to point the environment to.

Example:

# Point the staging environment to version 1.5.0
aws-static-deploy set-version staging 1.5.0

list-versions

Lists all deployed versions for the project from the S3 bucket.

aws-static-deploy list-versions

Example Workflow

1. Build your application.

   npm run build

2. Publish a new version. This uploads the contents of your dist folder to S3 under a new version and points staging to it.

   aws-static-deploy publish --minor

3. Test your staging environment. Verify that the new version works as expected on your staging URL.

4. Promote to production. Once you are confident, promote the staging version to be the live version.

   aws-static-deploy promote