{"id":16992,"library":"ember-cli-deploy-s3","title":"Ember CLI Deploy S3 Plugin","description":"ember-cli-deploy-s3 is an `ember-cli-deploy` plugin designed to upload static assets, such as JavaScript, CSS, images, and the `index.html` file, to an Amazon S3 bucket as part of an Ember CLI application's deployment pipeline. The current stable version is 5.0.1, with releases typically occurring as needed to address bugs, incorporate new features, or handle breaking changes in its underlying dependencies like the AWS SDK. Its primary differentiator is its seamless integration into the `ember-cli-deploy` ecosystem, providing a standardized way to handle asset deployment to S3 without manual scripting. It leverages the AWS SDK for credential resolution and S3 operations, with version 5.x adopting AWS SDK v3, which introduced significant changes compared to previous versions. Configuration is handled through the `config/deploy.js` file, allowing developers to specify S3 bucket details, access credentials, regions, and file patterns for upload.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/ember-cli-deploy/ember-cli-deploy-s3","tags":["javascript","ember-addon","ember-cli-deploy-plugin"],"install":[{"cmd":"npm install ember-cli-deploy-s3","lang":"bash","label":"npm"},{"cmd":"yarn add ember-cli-deploy-s3","lang":"bash","label":"yarn"},{"cmd":"pnpm add ember-cli-deploy-s3","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a prerequisite for the deployment pipeline to build the Ember application.","package":"ember-cli-deploy-build","optional":false},{"reason":"Underlying AWS SDK for S3 operations, migrated to v3 in ember-cli-deploy-s3 v5.0.0.","package":"@aws-sdk/client-s3","optional":false}],"imports":[{"note":"This plugin is configured declaratively in `config/deploy.js` by setting the `ENV.s3` property. There are no direct programmatic imports for its configuration.","wrong":"import { s3Config } from 'ember-cli-deploy-s3';","symbol":"s3 (configuration object)","correct":"ENV.s3 = {\n  accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',\n  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',\n  bucket: 'your-s3-bucket-name',\n  region: 'your-s3-bucket-region'\n};"},{"note":"While not typical for end-user applications, the plugin's main class might be default-exported for advanced use cases, testing, or internal extension. The plugin itself is integrated into the Ember CLI Deploy pipeline, not directly called from application code.","wrong":"const DeployS3Plugin = require('ember-cli-deploy-s3'); // CommonJS\nimport { DeployS3Plugin } from 'ember-cli-deploy-s3'; // Named vs Default","symbol":"DeployS3Plugin (internal)","correct":"import DeployS3Plugin from 'ember-cli-deploy-s3';"},{"note":"The plugin internally utilizes `S3Client` from `@aws-sdk/client-s3` (AWS SDK v3) for S3 interactions. This is relevant for understanding its underlying behavior and migration from older versions (v5.0.0+).","wrong":"import { S3 } from 'aws-sdk'; // AWS SDK v2 style","symbol":"S3Client (internal AWS SDK dependency)","correct":"// The plugin internally uses AWS SDK v3's S3Client.\nimport { S3Client } from '@aws-sdk/client-s3';"}],"quickstart":{"code":"ember install ember-cli-deploy-s3\n\n// config/deploy.js\nmodule.exports = function(deployTarget) {\n  const ENV = {\n    build: {},\n    s3: {\n      accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? 'YOUR_AWS_ACCESS_KEY',\n      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? 'YOUR_AWS_SECRET_KEY',\n      bucket: 'your-s3-bucket',\n      region: 'your-s3-bucket-region'\n    }\n  };\n\n  if (deployTarget === 'production') {\n    // Additional production-specific configuration\n  }\n\n  return ENV;\n};\n\n\n// Run the deployment\n// ember deploy","lang":"javascript","description":"This quickstart demonstrates how to install the plugin, configure it in `config/deploy.js` with essential AWS credentials and S3 bucket details, and the basic command to trigger a deployment."},"warnings":[{"fix":"Review AWS SDK documentation for v3 migration, update any custom code using AWS SDK directly to use `@aws-sdk/client-s3` and other modular clients, and ensure your deployment environment supports the new SDK.","message":"Version 5.0.0 introduced a breaking change by upgrading to AWS SDK v3. This changes how AWS services are initialized and called, moving from a monolithic `aws-sdk` package to modular `@aws-sdk/*` packages. Existing custom S3 client configurations or integrations relying on AWS SDK v2 will break.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Node.js environment to a supported version (14, 16, 18, or 20+) to meet the plugin's minimum requirements.","message":"Version 4.0.0 updated node version requirements (to `14.x || 16.x || 18.x || >= 20.*`) and other dependencies. Deployments on older Node.js versions will fail.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always define separate configuration objects for `ENV.s3` (for `ember-cli-deploy-s3`) and `ENV['s3-index']` (for `ember-cli-deploy-s3-index`), even if they contain similar properties.","message":"Sharing a single configuration object between `ember-cli-deploy-s3` and `ember-cli-deploy-s3-index` in `config/deploy.js` will lead to deployment failures due to side effects in how these plugins read their configuration.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure AWS credentials are correctly configured in your deployment environment (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` environment variables, `~/.aws/credentials` file, or appropriate IAM role for EC2 instances/containers). Explicitly providing `accessKeyId` and `secretAccessKey` in `config/deploy.js` can override this for testing but is generally not recommended for production.","message":"If `accessKeyId` and `secretAccessKey` are not explicitly defined, the plugin relies on the default AWS SDK credential resolution chain (e.g., environment variables, shared credentials file, IAM roles). Misconfiguration or missing credentials in these sources will result in authentication failures during deployment.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure that if you are using AWS STS, the `sessionToken` field in your `ENV.s3` configuration (or corresponding environment variable for SDK resolution) is correctly set. Upgrade to at least version 5.0.1 for robust `sessionToken` handling.","message":"When using temporary credentials via AWS Security Token Service (STS), `sessionToken` must be provided along with `accessKeyId` and `secretAccessKey`. Failing to provide the `sessionToken` will lead to authentication errors, even if the other credentials are correct. Version 5.0.1 included a fix to ensure the `sessionToken` is correctly passed to AWS credentials.","severity":"gotcha","affected_versions":">=5.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Update your `package.json` and `yarn.lock`/`package-lock.json` to ensure `@aws-sdk/client-s3` (and other related v3 packages) are correctly installed and that any custom S3 interaction code uses the new v3 API.","cause":"Attempting to use AWS SDK v2 patterns or an outdated `@aws-sdk/client-s3` package after upgrading to `ember-cli-deploy-s3` v5.0.0. The underlying AWS SDK changed from v2 to v3.","error":"Could not find `S3Client` in `@aws-sdk/client-s3`"},{"fix":"Ensure `ENV.s3.bucket` is defined with your S3 bucket name in `config/deploy.js`.","cause":"The `bucket` configuration option in `config/deploy.js` for the `s3` plugin is missing or empty.","error":"Missing required key 'bucket' in params"},{"fix":"Verify your AWS `accessKeyId`, `secretAccessKey`, and optionally `sessionToken`. Check the IAM user/role permissions for S3 actions (e.g., `s3:PutObject`, `s3:GetObjectAcl`, `s3:ListBucket`). Ensure the `region` is correctly set and matches your bucket.","cause":"AWS credentials (`accessKeyId`, `secretAccessKey`, `sessionToken` or resolved via profile/environment) are incorrect, missing, or lack the necessary permissions to perform S3 operations on the specified bucket/prefix.","error":"Access Denied"},{"fix":"Upgrade Node.js to version `14.x || 16.x || 18.x || >= 20.*` to meet the plugin's minimum requirements.","cause":"Using a Node.js version older than required by `ember-cli-deploy-s3` v4.0.0+.","error":"Node.js version x.y.z is not supported"},{"fix":"Define separate, distinct configuration objects for `ENV.s3` and `ENV['s3-index']` in `config/deploy.js`. Do not assign the same object reference to both.","cause":"Attempting to share a single configuration object between `ember-cli-deploy-s3` and `ember-cli-deploy-s3-index`, leading to conflicting state or unexpected side effects.","error":"Cannot read properties of undefined (reading 'upload')"}],"ecosystem":"npm","meta_description":null}