npm package: @mypolis.eu/aws-static-deploy
Description: CLI for deploying static websites to AWS S3 and CloudFront
Author: Guilherme Rosado
Latest version: 2.0.1

# 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

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

Or use it with `npx`:

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

## Configuration

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

```json
{
	"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:**

```bash
# 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.

```bash
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:**

```bash
# 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.

```bash
aws-static-deploy list-versions
```

## Example Workflow

1.  **Build your application.**

    ```bash
    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.

    ```bash
    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.
    ```bash
    aws-static-deploy promote
    ```