s3-deploy

library1.4.0jsnpmunverified

s3-deploy is a Node.js-based command-line utility designed for deploying files to Amazon S3 buckets and managing associated CloudFront cache invalidations. Currently at version 1.4.0, it appears to be actively maintained, indicated by the Greenkeeper badge, though a specific release cadence isn't published. Key differentiators include its robust handling of cache-control headers (including `max-age`, `immutable`, `no-cache`, and custom `Cache-Control`), automatic gzip compression for specified file types, and an option to prevent updates based on ETag matching. It's particularly useful for static site deployments where fine-grained caching and CDN invalidation are critical, providing a simplified bash-like interface over direct AWS SDK usage for common deployment tasks.

aws devops

npm install s3-deploy

github ↗package ↗

INSTALL

IMPORT

SIG · S3-DEPLOY

s3-deploy

awsjavascriptv1.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Deploys local build artifacts to S3, sets caching headers, gzips common file types, and invalidates CloudFront cache.

s3-deploy './build/**' \ --cwd './build/' \ --region us-east-1 \ --bucket my-static-website-bucket \ --distId E123EXAMPLEABC \ --invalidate '/*' \ --gzip 'html,css,js,svg,json' \ --cache 31536000 \ --immutable \ --preventUpdates

s3-deploy --version

Debug

Known issues

gotchaMultiple cache parameters (`--cache`, `--immutable`, `--noCache`, `--cacheControl`) can conflict. `--cacheControl` takes precedence over all others. If `--cacheControl` is not used, the precedence is `--noCache` > `--cache` > `--immutable`.

fix

Use only one cache-related parameter, or explicitly use `--cacheControl` for full customizability to avoid unintended behavior.

affects: >=1.0.0

gotchaThe `--preventUpdates` flag only ensures that an object either does not exist or has a matching ETag to be skipped. It does NOT prevent *all* modifications if the ETag differs; rather, it skips uploads where content hasn't changed. New files will still be uploaded, and files with different content (thus different ETags) will still be uploaded, effectively overwriting.

fix

Combine `--preventUpdates` with a robust CI/CD strategy or S3 bucket policies if absolute immutability is required.

affects: >=1.0.0

gotchaWhen using `--etag` without a specified value, the tool automatically calculates and uses the MD5 hash of the file content as the ETag header. If a specific ETag value is desired, it must be provided after the flag (e.g., `--etag MY_CUSTOM_ETAG`).

fix

Understand the behavior of `--etag` with and without a value. If you need a specific value, provide it; otherwise, rely on automatic MD5 hashing.

affects: >=1.0.0

gotchaFor CloudFront invalidation, the `--distId` parameter is mandatory. If omitted or incorrect, files may be deployed to S3, but users might continue to see old content due to cached versions in CloudFront edge locations.

fix

Ensure the correct CloudFront Distribution ID is provided with the `--distId` flag for successful cache invalidation.

affects: >=1.0.0

gotchaThe glob pattern (e.g., `'./dist/**'`) and the `--cwd` parameter are crucial. If the `--cwd` (current working directory) does not correctly align with the glob pattern, files may not be found or may be uploaded with incorrect S3 paths.

fix

Verify that your glob pattern correctly matches files relative to the `--cwd` path. Test with a dry run or small set of files first.

affects: >=1.0.0

Errors

Common errors & fixes

Error: InvalidParameter: Cache-Control header has conflicting directives

Using mutually exclusive cache parameters like `--noCache` and `--cache` or `--immutable` simultaneously.

fix

Remove conflicting cache control parameters. Prioritize `--cacheControl` if custom and complex caching rules are needed, or ensure only one of `--noCache`, `--cache`, or `--immutable` is used.

Access Denied

The AWS credentials used (via environment variables or AWS config) lack the necessary permissions to perform S3 putObject, getObject, or CloudFront createInvalidation operations.

fix

Review your AWS IAM policy. Ensure the user or role has `s3:PutObject`, `s3:GetObject`, `s3:ListBucket` (for `--preventUpdates`), and `cloudfront:CreateInvalidation` permissions for the target resources.

Error: No files found for pattern: './dist/**'

The glob pattern provided either doesn't match any files in the specified `--cwd`, or the `--cwd` path itself is incorrect.

fix

Double-check the glob pattern and the `--cwd` value. Ensure they correctly point to the files you intend to deploy relative to your execution directory.

CloudFrontInvalidation: Distribution E123EXAMPLEABC not found or invalid.

The provided `--distId` for CloudFront invalidation is either incorrect, doesn't exist, or the AWS credentials lack permission to access that distribution.

fix

Verify the CloudFront Distribution ID is correct. Ensure your AWS IAM user/role has `cloudfront:CreateInvalidation` permissions for the specified distribution.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/import-io/s3-deploy ↗

packagehttps://www.npmjs.com/package/s3-deploy ↗