{"id":13970,"library":"s3-deploy","title":"s3-deploy: AWS S3 & CloudFront Deployment Utility","description":"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.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/import-io/s3-deploy","tags":["javascript"],"install":[{"cmd":"npm install s3-deploy","lang":"bash","label":"npm"},{"cmd":"yarn add s3-deploy","lang":"bash","label":"yarn"},{"cmd":"pnpm add s3-deploy","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[],"quickstart":{"code":"s3-deploy './build/**' \\\n  --cwd './build/' \\\n  --region us-east-1 \\\n  --bucket my-static-website-bucket \\\n  --distId E123EXAMPLEABC \\\n  --invalidate '/*' \\\n  --gzip 'html,css,js,svg,json' \\\n  --cache 31536000 \\\n  --immutable \\\n  --preventUpdates\n","lang":"bash","description":"Deploys local build artifacts to S3, sets caching headers, gzips common file types, and invalidates CloudFront cache."},"warnings":[{"fix":"Use only one cache-related parameter, or explicitly use `--cacheControl` for full customizability to avoid unintended behavior.","message":"Multiple 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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Combine `--preventUpdates` with a robust CI/CD strategy or S3 bucket policies if absolute immutability is required.","message":"The `--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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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`).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the correct CloudFront Distribution ID is provided with the `--distId` flag for successful cache invalidation.","message":"For 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.4.0':37 'activ':42 'age':71 'amazon':25 'appear':39 'associ':30 'automat':81 'aw':4,125 'badg':48 'base':15,94 'bash':120 'bash-lik':119 'bucket':27 'cach':32,65,75,79,110 'cache-control':64,78 'cadenc':53 'cdn':112 'cloudfront':6,31 'command':17 'command-lin':16 'common':129 'compress':83 'control':66,80 'critic':115 'current':34 'custom':77 'deploy':3,7,11,22,105,130 'design':20 'differenti':58 'direct':124 'etag':96 'file':23,86 'fine':108 'fine-grain':107 'grain':109 'greenkeep':47 'gzip':82 'handl':62 'header':67 'immut':72 'includ':59,68 'indic':44 'interfac':122 'invalid':33,113 'isn':54 'javascript':132 'key':57 'like':121 'line':18 'maintain':43 'manag':29 'match':97 'max':70 'max-ag':69 'no-cach':73 'node.js':14 'option':90 'particular':100 'prevent':92 'provid':116 'publish':56 'releas':52 'robust':61 's3':2,5,10,26 's3-deploy':1,9 'sdk':126 'simplifi':118 'site':104 'specif':51 'specifi':85 'static':103 'task':131 'though':49 'type':87 'updat':93 'usag':127 'use':101 'util':8,19 'version':36","created_at":"2026-04-20T01:57:15.894200+00:00","updated_at":"2026-04-20T01:57:15.894200+00:00","problems":[{"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.","cause":"Using mutually exclusive cache parameters like `--noCache` and `--cache` or `--immutable` simultaneously.","error":"Error: InvalidParameter: Cache-Control header has conflicting directives"},{"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.","cause":"The AWS credentials used (via environment variables or AWS config) lack the necessary permissions to perform S3 putObject, getObject, or CloudFront createInvalidation operations.","error":"Access Denied"},{"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.","cause":"The glob pattern provided either doesn't match any files in the specified `--cwd`, or the `--cwd` path itself is incorrect.","error":"Error: No files found for pattern: './dist/**'"},{"fix":"Verify the CloudFront Distribution ID is correct. Ensure your AWS IAM user/role has `cloudfront:CreateInvalidation` permissions for the specified distribution.","cause":"The provided `--distId` for CloudFront invalidation is either incorrect, doesn't exist, or the AWS credentials lack permission to access that distribution.","error":"CloudFrontInvalidation: Distribution E123EXAMPLEABC not found or invalid."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"s3-deploy","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/import-io/s3-deploy","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/s3-deploy","openapi_spec":null,"status_page":null,"smithery":null,"categories":["aws","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-19","next_check":"2026-07-18","install_tag":null}}