UglifyJS

Common errors

• SyntaxError: Unexpected token: keyword 'const'

  cause Attempting to minify JavaScript code written with modern ES2015+ features (like `const`, `let`, arrow functions, classes) without prior transpilation to a UglifyJS-compatible syntax (primarily ES5).
  fix Pre-process your JavaScript files with a transpiler such as Babel to transform modern syntax into ES5 before passing them to `uglify-js`. Ensure your build configuration (e.g., Webpack, Gulp) includes this step.

• TypeError: UglifyJS.minify is not a function

  cause Incorrectly importing or requiring the `uglify-js` package, or attempting to call `minify` directly on the `UglifyJS` object without accessing the function property. In ESM, it could be trying `import UglifyJS from 'uglify-js'` and then `UglifyJS.minify()`.
  fix For CommonJS, use `const UglifyJS = require('uglify-js');` and then `UglifyJS.minify(code, options);`. For ESM, use `import { minify } from 'uglify-js';` and then `minify(code, options);`.

• Error: `return` outside of function

  cause The parser encountered a `return` statement in the global scope or within an IIFE/CommonJS module that is not explicitly wrapped as a function that UglifyJS recognizes.
  fix Include `parse: { bare_returns: true }` in your `minify` options to instruct UglifyJS to tolerate `return` statements outside of functions, which is common in certain module patterns.

• Cannot read properties of undefined (reading 'someProperty')

  cause This often occurs after aggressive property mangling (`--mangle-props` or `mangle.properties`) when UglifyJS renames object properties that are accessed dynamically (e.g., `obj['someProperty']`) or are external interfaces (like DOM properties or third-party library APIs) that should not be renamed.
  fix Use the `reserved` option within `mangle.properties` to specify a list of property names that should never be mangled. If mangling DOM properties, set `domprops: false`. Thoroughly test your application after enabling property mangling.

Warnings

• breaking UglifyJS 3 introduced a completely revised API and CLI that is not backward compatible with UglifyJS 2. Migrating from v2 requires updating import paths and usage patterns.
  Fix: Refer to the official UglifyJS 3 documentation for the new API and CLI usage. Specifically, `minify()` is the primary programmatic function.
• gotcha UglifyJS is designed primarily for ECMAScript 5 (ES5) and some later features. For code utilizing newer or 'exotic' ECMAScript features (e.g., ES2015+ syntax like optional chaining, nullish coalescing), it is critical to transpile the code down to a compatible syntax (e.g., ES5) using tools like Babel before feeding it to UglifyJS. Failure to do so can lead to `SyntaxError: Unexpected token` errors or incorrect minification.
  Fix: Integrate a transpilation step (e.g., Babel) into your build process to convert modern JavaScript syntax to ES5 or a compatible target before `uglify-js` processes the files.
• breaking Since v3.18.0, `uglify-js` processes input as an ES module by default (when using the `--module` CLI option or equivalent API setting). This can alter optimizations for existing CommonJS modules or scripts not explicitly marked as modules, potentially leading to different behavior or errors.
  Fix: If your input is CommonJS, ensure you explicitly disable ES module parsing by setting the appropriate option (e.g., `parse: { module: false }` in the `minify` options, or avoiding `--module` on the CLI) or verify your code's compatibility with ES module parsing.
• gotcha Aggressive property mangling (`--mangle-props` or `mangle.properties` option) can break code that relies on specific property names, especially when interacting with external APIs, DOM properties, or libraries that use string-based property access (e.g., `obj['myProp']`).
  Fix: Always use the `reserved` option within `mangle.properties` to specify property names that should *never* be mangled. For DOM properties, consider `domprops: false` or carefully use the `builtins` option. Thorough testing after mangling is essential.
• gotcha When minifying code that includes IIFEs (Immediately Invoked Function Expressions) or CommonJS modules, if a `return` statement appears outside of a function, UglifyJS may throw a 'Return outside of function' error.
  Fix: Set the `parse.bare_returns: true` option to allow return statements outside of functions. This is particularly useful for CommonJS modules or userscripts wrapped by an external caller.
• breaking Older versions of UglifyJS (prior to 2.6.0) had known Regular Expression Denial of Service (ReDoS) vulnerabilities in the `parse()` function.
  Fix: Upgrade `uglify-js` to version 2.6.0 or greater to mitigate ReDoS vulnerabilities. Regularly updating to the latest stable version is recommended for security patches.

Install

• npm install uglify-js npm
• yarn add uglify-js yarn
• pnpm add uglify-js pnpm

Imports

• minify
  wrong:

  const uglify = require('uglify-js');
  const result = uglify(...);

  correct:

  import { minify } from 'uglify-js';

  The primary programmatic entry point is the `minify` function, often accessed directly from the default export in CommonJS or as a named export in ESM. While `require('uglify-js')` returns an object containing `minify`, direct access is common.
• UglifyJS
  wrong:

  import UglifyJS from 'uglify-js';

  correct:

  const UglifyJS = require('uglify-js');

  For CommonJS environments, the entire UglifyJS toolkit is typically imported as a single object named `UglifyJS`, from which `minify` and other utilities are accessed. Native ESM default imports might not work as expected due to the package's primary CJS export.
• AST_Node

  const { AST_Node } = require('uglify-js');

  UglifyJS exposes its Abstract Syntax Tree (AST) nodes for advanced use cases like custom transformations. These are typically imported as named exports from the main package.

Quickstart

This quickstart demonstrates how to programmatically minify JavaScript code using `uglify-js`, including common compression and mangling options, and handling potential errors or warnings.

const UglifyJS = require('uglify-js');

const code = `
function greet(name) {
  const message = 'Hello, ' + name + '!';
  console.log(message);
  if (name === 'World') {
    return 'Special greeting';
  }
  return 'General greeting';
}

const myName = 'World';
greet(myName);
`;

const options = {
  compress: {
    dead_code: true,
    drop_console: true,
    reduce_vars: true
  },
  mangle: {
    toplevel: true,
    properties: false,
  },
  output: {
    comments: 'some',
    beautify: false,
  },
};

const result = UglifyJS.minify(code, options);

if (result.error) {
  console.error('Uglification Error:', result.error);
} else {
  console.log('Minified code:\n', result.code);
  if (result.warnings) {
    console.warn('Uglification Warnings:', result.warnings);
  }
}