Ember CLI Deploy Gzip Plugin

3.0.0 · active · verified Wed Apr 22

ember-cli-deploy-gzip is a plugin for the Ember CLI Deploy ecosystem, designed to perform in-place gzip compression of static assets as part of a deployment pipeline. Its primary function is to prepare files for upload to asset hosts that expect pre-compressed content, ensuring efficient delivery. The current stable version is 3.0.0, released recently with updated dependencies and Node.js version requirements, maintaining active development. While it does not follow a fixed release cadence, updates are typically driven by Ember CLI or Node.js compatibility needs, or bug fixes. A key differentiator is its seamless integration into the `ember-cli-deploy` workflow, allowing declarative configuration for which file types to compress, including an `ignorePattern` for specific exclusions. It also offers the option to use `node-zopfli` for stronger (though slower) compression. This plugin abstracts away the direct use of compression libraries, providing a higher-level, deployment-focused solution for Ember applications.

Common errors

```
Cannot find module 'node-zopfli'
```
cause The `zopfli` option was enabled in `config/deploy.js` (e.g., `gzip: { zopfli: true }`) but the `node-zopfli` package was not installed.

fix Install the `node-zopfli` package as a development dependency: `npm install node-zopfli --save-dev` or `yarn add node-zopfli --dev`.
```
The Ember CLI Deploy pipeline executed, but files are not being gzipped as expected.
```
cause Incorrect `filePattern` or `ignorePattern` configuration, or `ember-cli-deploy-gzip` is not properly included in the `plugins` array in `config/deploy.js`.

fix Review the `filePattern` and `ignorePattern` settings in your `config/deploy.js`. Verify that `'gzip'` is present in the `plugins` array. Also, check if `keep: false` is set and you are looking for `.gz` files instead of the originals.
```
Error: Node.js vX.X.X is not supported by ember-cli-deploy-gzip.
```
cause Your current Node.js version is incompatible with the installed version of `ember-cli-deploy-gzip`, particularly after the v3.0.0 breaking change.

fix Upgrade your Node.js environment to a compatible version (e.g., `14.x || 16.x || 18.x || >= 20.x`) or downgrade `ember-cli-deploy-gzip` to a compatible version if your project cannot upgrade Node.js.

Warnings

breaking Version 3.0.0 introduced breaking changes, primarily by updating internal dependencies and raising the minimum supported Node.js versions. Users on older Node.js runtimes (prior to 14.x) must upgrade.
Fix: Ensure your project's Node.js environment is at version `14.x || 16.x || 18.x || >= 20.x`. Update `npm` or `yarn` dependencies if encountering package resolution issues.
gotcha If the `zopfli` configuration option is set to `true` for stronger compression, the `node-zopfli` package must be manually installed as a development dependency. It is not bundled with `ember-cli-deploy-gzip`.
Fix: If `zopfli: true` is configured, run `npm install node-zopfli --save-dev` or `yarn add node-zopfli --dev` in your project.
gotcha Certain file types, particularly image formats like `.png`, `.jpg`, and `.gif`, are already highly compressed and should generally not be gzipped again. Doing so can sometimes increase file size or offer negligible gains.
Fix: Ensure your `filePattern` and `ignorePattern` configurations in `config/deploy.js` exclude already compressed asset types. The default `filePattern` intelligently avoids common image formats.
gotcha This plugin relies on the `distDir` and `distFiles` properties being present on the deployment `context` object. These are typically provided by the `ember-cli-deploy-build` plugin, which is a common prerequisite.
Fix: Ensure `ember-cli-deploy-build` is installed (`ember install ember-cli-deploy-build`) and correctly configured in your deployment pipeline before `ember-cli-deploy-gzip`.

Install

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

Imports

ember install command
wrong:
```
npm install ember-cli-deploy-gzip
```
correct:
```
ember install ember-cli-deploy-gzip
```
This command integrates the addon into your Ember CLI project's build and deploy pipeline, making it available for configuration.
Gzip plugin inclusion
wrong:
```
import { gzip } from 'ember-cli-deploy-gzip';
```
correct:
```
module.exports = function(deployTarget) { return { plugins: ['gzip'], ... }; };
```
Ember CLI Deploy plugins are configured by their short name ('gzip' in this case) within the `plugins` array of your `config/deploy.js`, not via standard JavaScript module imports.
Gzip plugin configuration
wrong:
```
app.import('node_modules/ember-cli-deploy-gzip/index.js');
```
correct:
```
module.exports = function(deployTarget) { return { gzip: { filePattern: '**/*.{js,css}' }, ... }; };
```
Specific options for the `gzip` plugin are defined as a top-level property (`gzip`) within the deployment configuration object in `config/deploy.js`.

Quickstart

This quickstart demonstrates how to install `ember-cli-deploy-gzip` and configure it within `config/deploy.js` for an Ember CLI Deploy pipeline, typically alongside `ember-cli-deploy-build` and an asset-upload plugin like `ember-cli-deploy-s3`.

// config/deploy.js
module.exports = function(deployTarget) {
  var ENV = {
    build: {
      environment: 'production'
    },
    gzip: {
      filePattern: '**/*.{js,css,json,ico,map,xml,txt,svg,eot,ttf}', // Default pattern
      // keep: true, // Example: keep original files and create .gz versions
      // zopfli: true // Example: use zopfli for stronger compression (requires `node-zopfli` install)
    }
  };

  if (deployTarget === 'production') {
    // Example: configure S3 deployment alongside gzip
    ENV.s3 = {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',
      bucket: 'your-production-asset-bucket',
      region: 'us-east-1'
    };
  }

  // Include the necessary plugins in the deployment pipeline
  ENV.plugins = ['build', 'gzip', 's3']; // 'build' and 's3' are common companions

  return ENV;
};

// Terminal commands
// 1. Ensure prerequisite Ember CLI Deploy plugins are installed (e.g., build, an asset host like s3)
// $ ember install ember-cli-deploy-build
// $ ember install ember-cli-deploy-s3
// 2. Install this gzip plugin
// $ ember install ember-cli-deploy-gzip
// 3. Run the deployment
// $ AWS_ACCESS_KEY_ID="YOUR_KEY" AWS_SECRET_ACCESS_KEY="YOUR_SECRET" ember deploy production

view raw JSON →