JavaScript Minification for Ember CLI

4.0.2 · active · verified Sun Apr 19

ember-cli-terser is an Ember CLI addon designed to integrate the Terser JavaScript minifier into the Ember CLI build pipeline. Its primary function is to automatically minify JavaScript files during production builds, thereby optimizing application size and improving loading performance. The current stable version is 4.0.2. Its release cadence is generally aligned with major versions of the underlying `terser` library and updates to the Ember CLI ecosystem, often involving necessary Node.js support changes. A key differentiator is its seamless integration into the Ember CLI environment, allowing developers to configure `terser` options directly within `ember-cli-build.js` without manual adjustments to the build process. It effectively supersedes older minifiers like UglifyJS, providing modern JavaScript minification capabilities for Ember applications.

Common errors

```
TypeError: Cannot read property 'options' of undefined (or similar errors related to terser configuration)
```
cause Incorrectly structured `terser` options or use of deprecated fields after upgrading `ember-cli-terser` to v4 (which uses `terser@5`), especially due to the removal of deep defaulting.

fix Carefully review the `terser` configuration object within your `ember-cli-build.js` against the `terser@5` documentation and the `ember-cli-terser` README. Ensure all options are correctly nested and adhere to the current API.
```
Minification not happening in development builds, or `ember serve` performance is slow.
```
cause `ember-cli-terser` is disabled by default for development builds to speed up compilation times.

fix If minification is desired in development, explicitly set `enabled: true` in the `ember-cli-terser` options within `ember-cli-build.js`. For production-like builds, use `ember build --environment=production`.
```
Error: Node.js version x.x.x is not supported by ember-cli-terser@4 (or similar Node.js version compatibility errors).
```
cause Attempting to use `ember-cli-terser` v4 with an unsupported Node.js version (e.g., 8, 9, 11, 13).

fix Upgrade your Node.js environment to a compatible version (10.*, 12.*, or >= 14) as specified in the package's `engines` field.
```
Application functionality breaks or behaves unexpectedly after minification.
```
cause Aggressive `terser` options (e.g., in `compress` or `mangle`) can sometimes alter JavaScript code in a way that conflicts with specific application logic or external libraries.

fix Gradually relax `terser` options in `ember-cli-build.js`, starting with `compress.sequences`, `compress.dead_code`, `mangle.safari10`, or by adding problematic files to the `exclude` array. Test thoroughly after each adjustment to pinpoint the problematic option.

Warnings

breaking Starting with v4.0.0, deep defaulting of minification options was removed. Users must now explicitly define all desired `terser` options.
Fix: Review your `ember-cli-build.js` configuration. Ensure all `terser` options (e.g., `compress`, `output`, `mangle`) are fully specified if you relied on previous implicit defaults. Consult the `terser@5` documentation for available options.
breaking `ember-cli-terser` v4.0.0 updated to `terser@5` via `broccoli-terser-sourcemap@4`. This upgrade may introduce compatibility issues with older `terser` options or behavior changes.
Fix: Verify that your `terser` configuration in `ember-cli-build.js` is compatible with `terser@5`. Consult the `terser` changelog for any breaking changes in option syntax or default behaviors between v4 and v5.
breaking `ember-cli-terser` v4.0.0 dropped support for Node.js versions 8, 9, 11, and 13. Running on these versions will lead to errors.
Fix: Upgrade your Node.js environment to a supported version: 10.*, 12.*, or >= 14.
gotcha Source maps are disabled by default for production builds in Ember CLI. Minified code in production may lack debugging information unless explicitly enabled.
Fix: To enable source maps for production, configure `sourcemaps: { enabled: true, extensions: ['js'] }` in your `ember-cli-build.js`. Additionally, you might use `hiddenSourceMap: true` within `ember-cli-terser` options to prevent source map URLs from being added to output files.

Install

npm install ember-cli-terser npm
yarn add ember-cli-terser yarn
pnpm add ember-cli-terser pnpm

Imports

ember-cli-terser
wrong:
```
import { terserConfig } from 'ember-cli-terser';
```
correct:
```
new EmberApp({ 'ember-cli-terser': { enabled: true, /* ... */ } });
```
This represents the top-level configuration object key within the `EmberApp` options in your `ember-cli-build.js`. `ember-cli-terser` does not expose direct JavaScript exports for import into application code; its usage is entirely through Ember CLI's build configuration.
terser
wrong:
```
import * as Terser from 'ember-cli-terser/terser';
```
correct:
```
new EmberApp({ 'ember-cli-terser': { terser: { compress: {}, output: {} } } });
```
This refers to the nested object within the `ember-cli-terser` configuration in `ember-cli-build.js` that directly passes options to the underlying `terser` minifier. It is not an importable symbol.
enabled
wrong:
```
import { enableMinification } from 'ember-cli-terser';
```
correct:
```
new EmberApp({ 'ember-cli-terser': { enabled: false } });
```
A boolean flag used within the `ember-cli-terser` configuration in `ember-cli-build.js` to explicitly enable or disable minification. Not an importable symbol.

Quickstart

Demonstrates how to install `ember-cli-terser` and configure its minification options, including Terser-specific settings and source map handling, within an Ember CLI project's `ember-cli-build.js` file.

// Terminal (run in your Ember CLI project root)
ember install ember-cli-terser

// ember-cli-build.js
const EmberApp = require('ember-cli/lib/broccoli/ember-app');
// If using Embroider, you might also have this:
// const { maybeEmbroider } = require('@embroider/test-setup');

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    // Configure ember-cli-terser options here
    'ember-cli-terser': {
      enabled: true, // Default: true for production builds, false for development
      exclude: ['vendor.js'], // Example: Exclude specific files from minification
      terser: {
        compress: {
          sequences: 50,
          dead_code: true,
          drop_console: process.env.EMBER_ENV === 'production' // Drop console logs only in production
        },
        output: {
          semicolons: false // Example: Omit semicolons where possible
        },
        mangle: {
          safari10: true // Specific fix for Safari 10 bugs
        }
      },
      // Options for broccoli-terser-sourcemap can also be top-level
      hiddenSourceMap: true // Prevents adding '//# sourceMappingURL' comments
    },
    // General EmberApp sourcemap configuration
    sourcemaps: {
      enabled: process.env.EMBER_ENV === 'production', // Enable sourcemaps only for production builds
      extensions: ['js']
    }
  });

  // If using Embroider:
  // return maybeEmbroider(app);

  return app;
};

view raw JSON →