Terser

Common errors

• SyntaxError: Unexpected token '...' (or similar for ES6+ features)

  cause Attempting to minify modern JavaScript (ES6+) with an older minifier like `uglify-js` instead of `terser`.
  fix Ensure `terser` is installed and configured as your JavaScript minifier in your build pipeline, and that `uglify-js` is not accidentally being used.

• TypeError: terser.minify is not a function

  cause Incorrectly importing or accessing the `minify` function, often due to a wrong CommonJS `require` pattern or an invalid default import in ESM.
  fix For ESM: `import { minify } from 'terser';`. For CommonJS: `const { minify } = require('terser');`

• Error: 'beautify' option is not recognized or has no effect

  cause Using the deprecated `beautify` option in `terser` which has been removed in favor of external formatters.
  fix Remove any `beautify` options from your `terser` configuration. Use a dedicated code formatter like Prettier instead for beautification.

Warnings

• breaking `uglify-es` is no longer maintained and `uglify-js` does not support ES6+ syntax. Projects using older minifiers for modern JavaScript should migrate to `terser` to avoid build failures or incorrect output.
  Fix: Replace `uglify-es` or `uglify-js` with `terser` in `package.json` and update build scripts accordingly.
• deprecated The `beautification` features in `terser` are being removed. Using beautify options may lead to unexpected behavior or future breakage. For code formatting, use a dedicated tool like Prettier.
  Fix: Remove any `beautify` related options from `terser` configuration. Integrate `prettier` into your development workflow for code formatting.
• gotcha When using the `terser` CLI, if you pass options *before* input files, you must separate them with a double dash (`--`) to prevent input files from being interpreted as option arguments.
  Fix: Command line usage: `terser --compress --mangle -- input.js` instead of `terser --compress --mangle input.js`.
• breaking Terser requires Node.js version 10 or higher. Running with older Node.js versions will result in errors or installation failures due to engine requirements.
  Fix: Upgrade your Node.js environment to version 10 or newer. Check your `package.json` `engines` field for compatibility.

Install

• npm install terser npm
• yarn add terser yarn
• pnpm add terser pnpm

Imports

• minify
  wrong:

  const minify = require('terser').minify;

  correct:

  import { minify } from 'terser';

  CommonJS users typically destructure `minify` from the `require` call. ES Modules use named import for this function.
• MinifyOptions
  wrong:

  import { MinifyOptions } from 'terser';

  correct:

  import type { MinifyOptions } from 'terser';

  For TypeScript, use `import type` when importing only type definitions to ensure they are stripped during compilation and do not affect runtime.
• All exports (namespace import)
  wrong:

  import Terser from 'terser';

  correct:

  import * as Terser from 'terser';

  Terser does not provide a default export. If you need to access multiple exports or prefer a namespace import, use `import * as Terser from 'terser';` and then access functions like `Terser.minify`.

Quickstart

Demonstrates how to programmatically minify a JavaScript string using `terser`, including compression and mangling options for ES2020 syntax.

import { minify } from 'terser';

const code = `
class Greeter {
  constructor(name) {
    this.name = name;
  }

  greet() {
    return 'Hello, ' + this.name + '!';
  }
}

const greeter = new Greeter('World');
console.log(greeter.greet());
`;

async function runMinification() {
  try {
    const result = await minify(code, {
      compress: {
        dead_code: true,
        drop_console: true,
        ecma: 2020
      },
      mangle: {
        toplevel: true
      }
    });
    if (result.error) {
      console.error('Minification Error:', result.error);
    } else {
      console.log('Minified Code:\n', result.code);
      // Expected output will be a highly compressed version of the input JS
      // e.g., 'class Greeter{constructor(e){this.name=e}greet(){return"Hello, "+this.name+"!"}}const greeter=new Greeter("World");console.log(greeter.greet());'
    }
  } catch (e) {
    console.error('Unexpected Error:', e);
  }
}

runMinification();