Ember CLI Deploy S3 Plugin

5.0.1 · active · verified Wed Apr 22

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.

Common errors

```
Could not find `S3Client` in `@aws-sdk/client-s3`
```
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.

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.
```
Missing required key 'bucket' in params
```
cause The `bucket` configuration option in `config/deploy.js` for the `s3` plugin is missing or empty.

fix Ensure `ENV.s3.bucket` is defined with your S3 bucket name in `config/deploy.js`.
```
Access Denied
```
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.

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.
```
Node.js version x.y.z is not supported
```
cause Using a Node.js version older than required by `ember-cli-deploy-s3` v4.0.0+.

fix Upgrade Node.js to version `14.x || 16.x || 18.x || >= 20.*` to meet the plugin's minimum requirements.
```
Cannot read properties of undefined (reading 'upload')
```
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.

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.

Warnings

breaking 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.
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.
breaking 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.
Fix: Upgrade your Node.js environment to a supported version (14, 16, 18, or 20+) to meet the plugin's minimum requirements.
gotcha 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.
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.
gotcha 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.
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.
gotcha 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.
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.

Install

npm install ember-cli-deploy-s3 npm
yarn add ember-cli-deploy-s3 yarn
pnpm add ember-cli-deploy-s3 pnpm

Imports

s3 (configuration object)

wrong:

import { s3Config } from 'ember-cli-deploy-s3';

correct:

ENV.s3 = {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',
  bucket: 'your-s3-bucket-name',
  region: 'your-s3-bucket-region'
};

This plugin is configured declaratively in `config/deploy.js` by setting the `ENV.s3` property. There are no direct programmatic imports for its configuration.

DeployS3Plugin (internal)
wrong:
```
const DeployS3Plugin = require('ember-cli-deploy-s3'); // CommonJS
import { DeployS3Plugin } from 'ember-cli-deploy-s3'; // Named vs Default
```
correct:
```
import DeployS3Plugin from 'ember-cli-deploy-s3';
```
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.
S3Client (internal AWS SDK dependency)
wrong:
```
import { S3 } from 'aws-sdk'; // AWS SDK v2 style
```
correct:
```
// The plugin internally uses AWS SDK v3's S3Client.
import { S3Client } from '@aws-sdk/client-s3';
```
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+).

Quickstart

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.

ember install ember-cli-deploy-s3

// config/deploy.js
module.exports = function(deployTarget) {
  const ENV = {
    build: {},
    s3: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? 'YOUR_AWS_ACCESS_KEY',
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? 'YOUR_AWS_SECRET_KEY',
      bucket: 'your-s3-bucket',
      region: 'your-s3-bucket-region'
    }
  };

  if (deployTarget === 'production') {
    // Additional production-specific configuration
  }

  return ENV;
};


// Run the deployment
// ember deploy

view raw JSON →