@evokegroup/aws-deployment v2.1.9

@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

{
  "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

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

Deployment Step: cloudFront.invalidate

Invalidates paths within a CloudFront distribution

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

Deployment Step: s3.archive

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

{
  "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

{
  "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.

{
  "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

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.

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

Deployment Step: s3.uploadFiles

Uploads a directory to S3.

{
  "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"
      }
    }]
  }
}