❤
npm
Sign UpSign In

@evokegroup/aws-deployment

2.1.9 • Public • Published

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

Readme

Keywords

none

Package Sidebar

Install

npm i @evokegroup/aws-deployment

Weekly Downloads

39

Version

2.1.9

License

ISC

Unpacked Size

73 kB

Total Files

19

Last publish

Collaborators

  • ybevoke
  • jtsuyuki
  • evokejames
  • evoke-cjamodeo
Try on RunKit
Report malware