@evokegroup/aws-deployment

Provides AWS deployments via JSON configuration files. JSON with comments is supported when the file extension is .jsonc. Settings in the format ${VARIABLE_NAME} will be replaced with the environment variable value.

// config.json
{
  "settings": {
    "cloudFront": {
      "id": "${CLOUDFRONT_DISTRIBUTION_ID}"
    },
    "s3": {
      "bucket": "${S3_BUCKET_NAME}"
    }
  },
  "deployment": {
    "steps": {
      "s3.uploadFiles": {
        "directory": "static/dist",
        "ignore": [
          "^.*\\.htaccess$"
        ]
      },
      "s3.redirects": {
        "redirects": "aws-redirects.jsonc"
      },
      "s3.redirectionRules": {
        "rules": "aws-redirection-rules.json"
      },
      "cloudFront.invalidate": {},
      "s3.removeNotDeployed": {}
    }
  }
}

const awsDeploy = require('@evokegroup/aws-deployment');
awsDeploy({
  config: 'config.json'
})
  .then(() => {
    // done
  })
  .catch((err) => {
    // error
  });

The deployment can perform the same step multiple times by setting deployment.steps to an Array<object>.

// config.json
{
  "deployment": {
    "steps": [{
      "s3.uploadFiles": {
        "bucket": "${S3_BUCKET_ENGLISH}",
        "directory": "static/dist",
        "ignore": [
          "^fr\\/.*$"
        ]
      }
    }, {
      "s3.uploadFiles": {
        "bucket": "${S3_BUCKET_FRENCH}",
        "directory": "static/dist/fr"
      }
    }]
  }
}

Settings: CloudFront

Property	Type	Default	Description
id	`string`	`${CLOUDFRONT_DISTRIBUTION_ID}`	The CloudFront distribution ID or environment variable name as ${ENV_VAR_NAME}
paths	`Array<string>`	`["/*"]`	The invalidation paths

{
  "settings": {
    "cloudFront": {
      "id": "ABC123"
    }
  }
}

{
  "settings": {
    "cloudFront": {
      "id": "${CLOUDFRONT_ID}"
    }
  }
}


## Settings: S3
  
| Property | Type | Default | Description |
| -------- | ---- | ------- | ----------- |
| bucket | `string` | `${S3_BUCKET_NAME}` | The S3 bucket name or environment variable name as ${ENV_VAR_NAME} |
  
  
```json
{
  "settings": {
    "s3": {
      "bucket": "bucket-name",
    }
  }
}

{
  "settings": {
    "s3": {
      "bucket": "${S3_BUCKET_NAME}",
    }
  }
}

Deployment Step: All Steps

Property	Type	Default	Description
enabled	`boolean`	`true`	Is the step enabled

{
  "deployment": {
    "steps": {
      "step.name": {
        "enabled": true
      }
    }
  }
}

Deployment Step: cloudFront.invalidate

Invalidates paths within a CloudFront distribution

Property	Type	Default	Description
id	`string`	`settings.cloudFront.id`	The CloudFront distribution id
paths	`Array<string>`	`settings.cloudFront.paths`	The invalidation paths

{
  "deployment": {
    "steps": {
      "cloudFront.invalidate": {
        "id": "OVERRIDE",
        "paths": ["OVERRIDE"]
      }
    }
  }
}

Deployment Step: s3.archive

Creates a zip archive and uploads it to an S3 bucket.

Property	Type	Default	Description
bucket	`string`	`settings.s3.bucket`	The S3 bucket name
prefix	`string`		A bucket path prefix to append to to key
directory	`string`		The directory containing the files to upload
fileName	`string`		The generated ZIP file name. If this is `undefined`, `null` or empty, a file name will be automatically generated based on other settings.
separator	`string`	`_`	File name separator
timestamp	`boolean`	`false`	Append a timestamp to the file name. Defaults to and ISO string with `:` and `.` replaced with `-`.
timestampFormat	`string`		The date/time format string. See `@evokegroup/dateformat`.
timestampRadix	`number`		The radix to use for converting the `Date` into a string when a `timestampFormat` is not specified.
guid	`boolean`	`false`	Appends a guid to the file name.
ignore	`Array<string>`, `Array<RegExp>`	`[]`	Files to ignore when uploading

{
  "s3.archive": {
    "enabled": "${S3_ARCHIVE_ENABLED}",
    "bucket": "${S3_ARCHIVE}",
    "directory": "static/dist",
    "fileName": "archive",
    "timestamp": true
  }
}

Deployment Step: s3.redirectionRules

Sets the static website host redirection rules property.

See https://docs.aws.amazon.com/AmazonS3/latest/dev/how-to-page-redirect.html#advanced-conditional-redirects

Property	Type	Default	Description
bucket	`string`	`settings.s3.bucket`	The S3 bucket name
rules	`Array<object>`, `string`	An array of objects or a file containing the redirection rules.

{
  "deployment": {
    "steps": {
      "s3.redirectionRules": {
        "bucket": "OVERRIDE",
        "rules": "aws-redirection-rules.json"
      }
    }
  }
}

Deployment Step: s3.redirects

Creates redirects in S3 by creating an empty file with the redirect specified in it's metadata.

Property	Type	Default	Description
bucket	`string`	`settings.s3.bucket`	The S3 bucket name
redirects	`object`, `string`	`{}`	An object or a file containing the paths to be redirected and the redirect locations

{
  "deployment": {
    "steps": {
      "s3.redirects": {
        "bucket": "OVERRIDE",
        "redirects": "aws-redirects.jsonc"
      }
    }
  }
}

// aws-redirects.jsonc
{
  // Comments are supported in .jsonc file
  "/some-page": "/somewhere-else", 
  "/another-page": {
    "subpaths": ["index", "index.html"], // redirect /another-path/index and /another-path/index.html
    "redirect": "/go-here",
    "meta": {
      "Cache-Control": "max-age=3600, no-transform, public"
    }
  }
}

Redirect Object

Property	Type	Default	Description
key	`string`		The path to be redirected. A leading `/` is optional.
value	`object`, `string`		The path to redirect to or an object containing the redirect information. The redirect path should start with `/` if not redirecting to another domain.
value.alts	`Array<string>`		An array of alternate paths to be redirected.
value.exts	`Array<string>`		An array of extensions to append to the path to be redirected.
value.subpaths	`Array<string>`		An array of subpaths that should also be redirected.
value.redirect	`string`		The redirect path.
value.query	`object`		Query string data object
value.meta	`object`		Override S3 metadata
value.redirectHeader	`string`	`x-amz-website-redirect-location`	The redirect header name. Override this if using the standard S3 object redirection method in not desired and the redirection will be provided by another means.
value.track	`boolean`	`false`	Add tracking info
value.trackMethod	`string`	`querystring`	Add tracking info via `querystring` or `header`
value.trackData	`object`, `string`	`evo_redirected=${from}`	Tracking data. `string` values must be in the standard query string format. Values of `${from}` will be replaced with the path being redirected. Values of `${to}` will be replaced with the path being redirected to.

Basic redirect.

{
  "/vanity-url": "/real-url/?utm_source=test"
}

Redirect /vanity-url, /vanity-url.html, and /vanity-url/index.html.

{
  "/vanity-url": {
    "alts": [
      "/vanity-url.html",
      "/vanity-url/index.html"
    ],
    "redirect": "/real-url/",
    "query": {
      "utm_source": "test"
    }
  }
}

Redirect /external-url, /external-url.html, and /external-url/index.html and do not track.

{
  "/external-url": {
    "exts": [
      ".html"
    ],
    "subpaths": [
      "index.html"
    ],
    "redirect": "https://www.domain.com/path?other=data",
    "track": false
  }
}

Set tracking for all redirects.

{
  "deployment": {
    "steps": {
      "s3.redirects": {
        "redirects": "aws-redirects.jsonc",
        "track": true,
        "trackData": "from=${from}"
      }
    }
  }
}

Don't use an external file.

{
  "deployment": {
    "steps": {
      "s3.redirects": {
        "redirects": {
          "/redirect-me": "/go-here/"
        },
        "track": true,
        "trackData": {
          "from": "${from}",
          "to": "${to}"
        }
      }
    }
  }
}

Deployment Step: s3.removeNotDeployed

Removes any files not included in the deployment.

Property	Type	Default	Description
bucket	`string`	`settings.s3.bucket`	The S3 bucket name
removeFiles	`boolean`	`true`	Remove files
removeRedirects	`boolean`	`true`	Remove redirects
removeAnyCreator	`boolean`	`true`	Remove a file or redirect regardless of how the file was created. To remove only files created with the library set to `false`
ignore	`Array<RegExp>`	`[]`	An array of regular expressions of files that should not be deleted

{
  "deployment": {
    "steps": {
      "s3.removeNotDeployed": {
        "bucket": "OVERRIDE",
        "ignore": [
          "^do-not-delete.txt$"
        ]
      }
    }
  }
}

Deployment Step: s3.uploadFiles

Uploads a directory to S3.

Property	Type	Default	Description
bucket	`string`	`settings.s3.bucket`	The S3 bucket name
prefix	`string`		A bucket path prefix to add to every file
directory	`string`	`null`	The directory containing the files to upload
ignore	`Array<RegExp>`	`[]`	Files to ignore when uploading
meta	`object`	`{}`	S3 metadata. Extends the standard configuration (`services.s3.meta`)
onlyChanged	`boolean`	`true`	Only upload files who's ETag is different

{
  "deployment": {
    "steps": {
      "s3.uploadFiles": {
        "bucket": "OVERRIDE",
        "directory": "static/dist",
        "ignore": [
          "^.*\\.htaccess$"
        ]
      }
    }
  }
}

Upload to multiple buckets

{
  "deployment": {
    "steps": [{
      "s3.uploadFiles": {
        "bucket": "${S3_BUCKET_ENGLISH}",
        "directory": "static/dist",
        "ignore": [
          "^fr\\/.*$"
        ]
      }
    }, {
      "s3.uploadFiles": {
        "bucket": "${S3_BUCKET_FRENCH}",
        "directory": "static/dist/fr"
      }
    }]
  }
}