AWS Static Deploy CLI

CLI for publishing versioned static website releases to Amazon S3 and CloudFront KeyValueStore.

This tool uploads immutable assets to S3 and changes release-pointer keys in an existing CloudFront KeyValueStore. It does not create or update persistent infrastructure.

Features

• Uploads build assets to an immutable, versioned S3 path.
• Supports semantic version bumps for patch, minor, and major releases.
• Sets the staging release pointer after a successful publish.
• Moves the staging release pointer to latest with promote.
• Sets other release pointers with set-version.
• Supports Gzip and Brotli compression.
• Requires an existing CloudFront KeyValueStore ARN.

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/00000000-0000-0000-0000-000000000000"
	},
	"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 project name. The CLI uses it as the 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 the CloudFront KeyValueStore data plane.
• aws.s3BucketName: The name of the existing S3 bucket.
• aws.kvsArn: The ARN of the existing CloudFront KeyValueStore. This field is required. The CLI fails if it is absent or invalid.
• 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 Setup

Required infrastructure

A platform owner must supply the bucket and KeyValueStore ARN. The platform owner must also configure CloudFront routing. The CLI does not discover resources by name, and it does not create, update, or publish CloudFront resources.

IAM permissions

Give the release identity access only to its project prefix and to the configured KeyValueStore. Replace all placeholders in this example:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ListProjectVersions",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::{s3BucketName}",
            "Condition": {
                "StringLike": {
                    "s3:prefix": [
                        "{projectName}/*"
                    ]
                }
            }
        },
        {
            "Sid": "UploadImmutableProjectAssets",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:AbortMultipartUpload",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": "arn:aws:s3:::{s3BucketName}/{projectName}/*"
        },
        {
            "Sid": "ReadAndUpdateReleasePointers",
            "Effect": "Allow",
            "Action": [
                "cloudfront-keyvaluestore:DescribeKeyValueStore",
                "cloudfront-keyvaluestore:GetKey",
                "cloudfront-keyvaluestore:UpdateKeys"
            ],
            "Resource": "{kvsArn}"
        }
    ]
}

Usage

--version

Prints the installed CLI version. This option does not require a deploy.config.json file.

aws-static-deploy --version

publish [versionNumber]

Uploads a new immutable version to S3 and sets the staging pointer to the new version. It does not reconcile infrastructure.

If [versionNumber] is not provided, it automatically bumps the latest version found in S3. 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 by updating the latest key in the KeyValueStore.

aws-static-deploy promote

set-version <environment> <versionNumber>

Manually points an environment to a specific, existing version.

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

list-versions

Lists all deployed versions for the project, showing which are staging and which are latest.

aws-static-deploy list-versions

Example Workflow

1. Create your config file (deploy.config.json).

2. Build your application.

   npm run build

3. Publish a new version.

   aws-static-deploy publish --minor

4. Test staging.

   curl -H "x-environment: staging" https://your-distribution.cloudfront.net/

5. Promote to production.

   aws-static-deploy promote