Grunt Uglify Plugin

5.2.2 · active · verified Sun Apr 19

grunt-contrib-uglify is a Grunt plugin designed to minify JavaScript files efficiently using the UglifyJS library. As of its current stable version, 5.2.2, it provides a crucial build step for optimizing frontend assets by reducing file sizes. The package typically sees releases driven by updates to its underlying dependencies, particularly UglifyJS, or to maintain compatibility with newer Node.js and Grunt versions, rather than a fixed release cadence. Its primary differentiator is its deep integration into the Grunt task runner ecosystem, allowing developers to configure JavaScript minification directly within their Gruntfiles with fine-grained control over UglifyJS options like mangling, compression, and source map generation. This makes it a go-to solution for projects that leverage Grunt for their build automation, abstracting the complexities of direct UglifyJS CLI usage into a declarative task configuration.

Common errors

```
Loading "uglify.js" tasks...ERROR
```
cause The `grunt-contrib-uglify` plugin was not correctly installed or loaded in the Gruntfile.

fix Ensure `npm install grunt-contrib-uglify --save-dev` has been run and `grunt.loadNpmTasks('grunt-contrib-uglify');` is present in your Gruntfile.js.
```
Fatal error: UglifyJS minification failed.
```
cause This usually indicates a syntax error in the input JavaScript file(s) that UglifyJS cannot parse, or an incompatibility between your JavaScript syntax and the UglifyJS version being used.

fix Check the detailed error message for line numbers and specific syntax issues. If using modern JavaScript (ES6+), ensure it's properly transpiled before UglifyJS processes it, or verify that your `uglify-js` dependency (and thus `grunt-contrib-uglify`) is up-to-date enough to support the syntax.
```
Error: Node Sass does not yet support your current Node.js version.
```
cause While not directly from `grunt-contrib-uglify`, this error often occurs in Grunt projects when one `grunt-contrib` plugin (or other dependency) has a strict Node.js version requirement that conflicts with another, or the overall project's Node.js version is too old for its dependencies.

fix Review all `devDependencies` for specific Node.js compatibility matrixes. Update Node.js to a version compatible with all project dependencies, or downgrade conflicting dependencies.

Warnings

breaking Node.js version requirements have increased over time. Version 4.0.0 required Node.js >=6, version 5.0.0 required Node.js >=10, and version 5.1.0 and above require Node.js >=12. Ensure your Node.js environment meets these minimums to avoid installation or runtime errors.
Fix: Upgrade your Node.js installation to version 12 or newer (e.g., using nvm).
deprecated Several options from `grunt-contrib-uglify` 2.x have been deprecated and replaced or removed in 3.x and later versions, including `ASCIIOnly`, `enclose`, `exportAll`, `expression`, `indentLevel`, `mangleProperties`, `maxLineLen`, `preserveComments`, `quoteStyle`, `screwIE8`, `sourceMapIncludeSources`, `sourceMapRoot`, and `sourceMapUrl`.
Fix: Refer to the `uglify-js` documentation for the equivalent options under `output`, `parse`, `mangle`, and `sourceMap` configurations. For example, `ASCIIOnly` is now `output.ascii_only` and `preserveComments` is `output.comments`.
gotcha The `report: 'gzip'` option significantly increases task execution time (5-10x longer) because it performs Gzip compression on the minified output for reporting purposes. While useful for detailed size analysis, it's not recommended for routine builds or watch tasks.
Fix: Use the default `report: 'min'` for faster builds, or only enable `report: 'gzip'` when specific size analysis is required.
gotcha This plugin wraps UglifyJS. While `uglify-js` itself supports most ECMAScript features, for more 'exotic' or bleeding-edge ES2015+ (ES6+) features, or certain older `uglify-js` versions, you might need to transpile your JavaScript with tools like Babel *before* passing it to `grunt-contrib-uglify` to prevent parsing errors or unexpected minification results.
Fix: If encountering parsing errors with modern JavaScript syntax, integrate a transpilation step (e.g., using `grunt-babel`) into your Grunt workflow before the `uglify` task.

Install

npm install grunt-contrib-uglify npm
yarn add grunt-contrib-uglify yarn
pnpm add grunt-contrib-uglify pnpm

Imports

uglify
wrong:
```
import { uglify } from 'grunt-contrib-uglify';
const uglify = require('grunt-contrib-uglify');
```
correct:
```
grunt.loadNpmTasks('grunt-contrib-uglify');
```
This package is a Grunt plugin, not a standard JavaScript module. It is loaded directly into the Grunt runtime within your Gruntfile, typically with `loadNpmTasks`.

Quickstart

This Gruntfile.js example configures the `uglify` task to minify and concatenate two JavaScript files into one, adding a banner and generating a source map. It then defines a default task to run `uglify`.

module.exports = function(grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    uglify: {
      options: {
        banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n',
        sourceMap: true,
        sourceMapName: 'dist/app.min.js.map'
      },
      my_target: {
        files: {
          'dist/app.min.js': ['src/js/module1.js', 'src/js/module2.js']
        }
      }
    }
  });

  // Load the plugin that provides the "uglify" task.
  grunt.loadNpmTasks('grunt-contrib-uglify');

  // Default task(s).
  grunt.registerTask('default', ['uglify']);
};

view raw JSON →