Ember CLI Deploy CloudFront Cache Invalidation

6.0.0 verified Thu Apr 23 auth: no javascript

`ember-cli-deploy-cloudfront` is an `ember-cli-deploy` plugin designed to automate the invalidation of cached files on AWS CloudFront distributions as part of an Ember application's continuous deployment pipeline. The current stable version is 6.0.0, which notably updates the underlying AWS SDK to v3. The package's release cadence is tied to Node.js LTS support and critical dependency upgrades, such as the AWS SDK. Its primary use case is invalidating `index.html` after a new deployment, though it supports invalidating multiple custom paths and multiple CloudFront distributions. It differentiates itself by providing seamless integration into the `ember-cli-deploy` ecosystem, allowing developers to manage CloudFront cache busts directly from their Ember CLI projects without manual AWS console intervention. It supports various AWS authentication methods, including access keys, IAM roles, and profiles.

Common errors

error Missing credentials in config, if using profile make sure region is defined ↓

cause The AWS SDK failed to find valid credentials for authentication. This can happen if required `accessKeyId` and `secretAccessKey` are not provided, or if a `profile` is specified without a corresponding `region` or without the profile being correctly configured.

fix

Ensure accessKeyId and secretAccessKey are set in config/deploy.js, or that a valid profile with an associated region is configured in ~/.aws/credentials, or that environment variables like AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are present and accessible.

error InvalidationBatch contains 0 items ↓

cause The `objectPaths` configuration in `config/deploy.js` is empty or does not contain any valid paths for invalidation. CloudFront requires at least one object path to invalidate.

fix

Verify that objectPaths in config/deploy.js is correctly configured with valid paths (e.g., ['/index.html', '/assets/*']). Remember that all object paths must be relative to the CloudFront distribution root and begin with /.

error The CloudFront distribution was not found. (DistributionIdNotFound) ↓

cause The `distribution` ID configured in `config/deploy.js` is incorrect, misspelled, or does not exist in the AWS account associated with the provided credentials.

fix

Double-check the distribution ID in your config/deploy.js against your AWS CloudFront console to ensure it is accurate and belongs to the correct AWS account/region.

error User: arn:aws:iam::... is not authorized to perform: cloudfront:CreateInvalidation on resource: arn:aws:cloudfront::.../distribution/... ↓

cause The IAM user or role associated with the AWS credentials used by the plugin lacks the necessary permissions to create CloudFront invalidations for the specified distribution.

fix

Grant the required cloudfront:CreateInvalidation permission to the IAM user or role whose credentials are being used by the ember-cli-deploy-cloudfront plugin in your AWS IAM console.

Warnings

breaking Minimum Node.js version has been progressively increased across major versions. `ember-cli-deploy-cloudfront@6.x` requires Node.js `16.* || 18.* || >= 20`. Earlier versions of the plugin dropped support for Node 6 (v2), Node 8 (v3), Node 10 (v4), and Node 12 (v5). ↓

fix Ensure your deployment environment uses a compatible Node.js version (16+ for v6.x). Upgrade Node.js if necessary.

breaking `ember-cli-deploy-cloudfront@6.0.0` upgraded the underlying AWS SDK from v2 to v3. This introduces breaking changes in the SDK's API, which will affect any custom `invalidationClient` implementations or direct interactions with the SDK. ↓

fix If you have implemented a custom `invalidationClient`, you must update your code to use the AWS SDK v3 API for `CloudFrontClient` and related commands. Refer to the AWS SDK for JavaScript v3 documentation for migration guides.

gotcha AWS credentials (e.g., `accessKeyId`, `secretAccessKey`, `profile`) are resolved by the AWS SDK in a specific order. Explicitly setting `accessKeyId` and `secretAccessKey` directly in `config/deploy.js` will override environment variables or profile settings, which might lead to unexpected behavior. ↓

fix Carefully review the AWS SDK credential resolution documentation to understand the precedence. For production environments, consider using IAM roles for EC2 instances or OIDC for GitHub Actions instead of hardcoding keys or relying solely on local profiles.

Install

npm install ember-cli-deploy-cloudfront

yarn add ember-cli-deploy-cloudfront

pnpm add ember-cli-deploy-cloudfront

Imports

CloudFrontClient
wrong
```
const { CloudFront } = require('aws-sdk');
```
correct
```
import { CloudFrontClient } from '@aws-sdk/client-cloudfront';
```
While `ember-cli-deploy-cloudfront` itself is a plugin configured via `config/deploy.js` and not typically imported directly, developers might need to import `CloudFrontClient` when implementing a custom `invalidationClient` option, especially with the AWS SDK v3 update in `6.0.0`.
CreateInvalidationCommand
wrong
```
const CreateInvalidationCommand = require('aws-sdk/clients/cloudfront').CreateInvalidationCommand;
```
correct
```
import { CreateInvalidationCommand } from '@aws-sdk/client-cloudfront';
```
Similar to `CloudFrontClient`, this command is relevant if a custom `invalidationClient` is being developed to programmatically create invalidations using AWS SDK v3 for `ember-cli-deploy-cloudfront@6.x`.
CloudFrontClientConfig
```
import { CloudFrontClientConfig } from '@aws-sdk/client-cloudfront';
```
This TypeScript type is useful for developers who are creating custom `invalidationClient` implementations and need to type their configuration objects for the AWS SDK v3 client.

Quickstart

This quickstart demonstrates how to install `ember-cli-deploy-cloudfront` and configure it in `config/deploy.js` to invalidate `index.html` and other assets on a specified CloudFront distribution after deployment, using environment variables for sensitive AWS credentials.

/* config/deploy.js */
module.exports = function(deployTarget) {
  const ENV = {
    build: {
      environment: deployTarget
    },
    'cdn-url': {
      // Example for a paired s3-index plugin, typically used with cloudfront
      url: process.env.CDN_URL || 'https://your-cloudfront-distribution-domain.com'
    },
    cloudfront: {
      // Recommended: use environment variables for sensitive credentials
      accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',
      distribution: process.env.CLOUDFRONT_DISTRIBUTION_ID ?? '', // REQUIRED: Your CloudFront Distribution ID
      region: process.env.AWS_REGION ?? 'us-east-1', // Specify your AWS region
      objectPaths: ['/index.html', '/assets/*'], // Paths to invalidate. Must start with '/'
      waitForInvalidation: true // Wait for the invalidation to complete (introduced in v2.0.0)
    }
  };
  // Add additional deploy target specific configuration here
  if (deployTarget === 'production') {
    // Specific production settings
  }
  return ENV;
};

// To install:
// ember install ember-cli-deploy-cloudfront

// To run deployment with activation:
// AWS_ACCESS_KEY_ID='YOUR_KEY' AWS_SECRET_ACCESS_KEY='YOUR_SECRET' CLOUDFRONT_DISTRIBUTION_ID='E123ABCDEFGH' ember deploy production --activate