grunt-ps-uglify

High-performance Grunt plugin for JavaScript minification using UglifyJS with parallel processing, intelligent caching, and performance monitoring.

Features

• 🚀 Parallel Processing: Process multiple files simultaneously for faster builds
• 💾 Intelligent Caching: Skip unchanged files with smart cache invalidation
• 📊 Performance Monitoring: Detailed performance metrics and recommendations
• 🗺️ Source Maps: Full source map support with customizable options
• ⚙️ Advanced Minification: Property mangling, compression, and beautification options
• 🔧 Worker Threads: CPU-intensive operations in separate threads for large files
• 📈 Benchmarking: Built-in performance comparison and optimization tools

Installation

npm install grunt-ps-uglify --save-dev

Getting Started

If you haven't used Grunt before, be sure to check out the Getting Started guide.

Once the plugin has been installed, enable it in your Gruntfile:

grunt.loadNpmTasks('grunt-ps-uglify');

Usage

Basic Configuration

grunt.initConfig({
  psUglify: {
    options: {
      // Global options
      parallel: true,
      performanceReport: true
    },
    dist: {
      files: {
        'dist/output.min.js': ['src/input1.js', 'src/input2.js']
      }
    }
  }
});

Advanced Configuration

grunt.initConfig({
  psUglify: {
    options: {
      banner: '/*! My Project <%= grunt.template.today("yyyy-mm-dd") %> */\n',
      parallel: true,
      performanceReport: true,
      performanceThreshold: 1000, // Log details if processing takes >1s
      compress: {
        drop_console: true,
        dead_code: true,
        unused: true
      },
      mangle: {
        toplevel: true,
        properties: {
          regex: /^_/
        }
      },
      sourceMap: {
        filename: 'dist/output.min.js.map',
        url: 'output.min.js.map',
        includeSources: true
      }
    },
    build: {
      files: {
        'dist/app.min.js': ['src/**/*.js']
      }
    }
  }
});

Options

Core Options

parallel

Type: Boolean
Default: true

Enable parallel processing for multiple files. Significantly faster for projects with many files.

performanceReport

Type: Boolean
Default: false

Enable detailed performance reporting including cache efficiency, memory usage, and optimization recommendations.

performanceThreshold

Type: Number
Default: 1000

Time threshold in milliseconds. Performance details are logged if processing takes longer than this value.

workerThreads

Type: Boolean
Default: undefined (auto-detection)

Enable worker threads for CPU-intensive operations. Set to true to force enable, false to disable, or leave undefined for automatic detection based on file size and complexity.

UglifyJS Options

compress

Type: Object|Boolean
Default: { keep_fargs: true }

Compression options passed to UglifyJS. See UglifyJS documentation for details.

compress: {
  drop_console: true,
  drop_debugger: true,
  dead_code: true,
  unused: true,
  join_vars: true
}

mangle

Type: Object|Boolean
Default: {}

Variable and property name mangling options.

mangle: {
  toplevel: true,
  reserved: ['$', 'exports', 'require'],
  properties: {
    regex: /^_/,
    reserved: ['$element', '$scope']
  }
}

beautify/output

Type: Object|Boolean
Default: false

Output formatting options. Set to true for default beautification or an object for custom options.

output: {
  beautify: true,
  indent_level: 2,
  max_line_len: 80,
  quote_style: 1 // 0=auto, 1=single, 2=double, 3=original
}

Source Map Options

sourceMap

Type: Object|Boolean
Default: false

Source map generation options.

sourceMap: {
  filename: 'output.js.map',
  url: 'output.js.map',
  root: '/src/',
  includeSources: true
}

sourceMapIn

Type: String|Function
Default: undefined

Input source map file path or function returning the path.

sourceMapName

Type: String|Function
Default: undefined

Custom source map filename or function generating the name.

Caching Options

nameCache

Type: String
Default: undefined

Path to JSON file for persistent name cache across builds.

exceptionsFiles

Type: Array
Default: undefined

Array of JSON files containing variables and properties to exclude from mangling.

exceptionsFiles: ['config/mangle-exceptions.json']

Example exceptions file:

{
  "vars": ["$", "jQuery", "angular"],
  "props": ["$scope", "$element", "$$watchers"]
}

Examples

Basic Minification

psUglify: {
  basic: {
    files: {
      'dist/app.min.js': ['src/app.js']
    }
  }
}

Multiple Files with Source Maps

psUglify: {
  build: {
    options: {
      sourceMap: {
        filename: 'dist/bundle.js.map',
        includeSources: true
      },
      compress: {
        drop_console: true
      }
    },
    files: {
      'dist/bundle.min.js': ['src/**/*.js']
    }
  }
}

Advanced Property Mangling

psUglify: {
  advanced: {
    options: {
      mangle: {
        properties: {
          regex: /^_/,
          reserved: ['_super', '_initialize']
        }
      },
      nameCache: 'tmp/uglify-cache.json',
      exceptionsFiles: ['config/mangle-exceptions.json']
    },
    files: {
      'dist/app.min.js': ['src/**/*.js']
    }
  }
}

Performance Optimized Build

psUglify: {
  options: {
    parallel: true,
    workerThreads: true,
    performanceReport: true,
    compress: {
      passes: 2,
      drop_console: true,
      dead_code: true
    }
  },
  dist: {
    files: [
      {
        expand: true,
        cwd: 'src/',
        src: '**/*.js',
        dest: 'dist/',
        ext: '.min.js'
      }
    ]
  }
}

Performance Features

Parallel Processing

The plugin automatically processes multiple files in parallel, significantly reducing build times for large projects:

Sequential: 5.432s
Parallel:   1.847s (66% faster)

Note: Performance improvements vary based on system specs, file sizes, and project complexity.

Intelligent Caching

Files are cached based on content hash and options. Unchanged files are skipped:

Cache: 156 hits, 12 misses (92.3% efficiency)
Time saved: 3.2s

Note: Cache efficiency depends on your development workflow and file change patterns.

Performance Monitoring

Enable detailed performance reports:

options: {
  performanceReport: true,
  performanceThreshold: 500
}

Example output:

📊 Performance Report:
   Total time: 2.341s
   Parallel processing: 1.847s
   Cache operations: 0.123s
   Files processed: 45
   Cache efficiency: 156 hits, 12 misses
   Compression ratio: 68.4%
   💡 Recommendation: Enable worker threads for better performance on large files

Worker Threads

For CPU-intensive operations on large files, the plugin can utilize worker threads:

options: {
  workerThreads: true, // or leave undefined for automatic detection
  parallel: true
}

Benchmarking

Run performance benchmarks:

npm run benchmark

API

The plugin registers the psUglify task which can be configured as a multi-task in your Gruntfile.

Requirements

• Node.js >= 18.0.0
• Grunt >= 1.0.0

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run the test suite: npm test
5. Run performance tests: npm run test:performance
6. Submit a pull request

Development Commands

# Run tests
npm test

# Run tests with verbose output
npm run test:verbose

# Run performance tests
npm run test:performance

# Run benchmarks
npm run benchmark

# Validate everything
npm run validate

Changelog

See the releases page for release history.

License

Licensed under the MIT License.

Credits

Built with ❤️ by Peter Selvaraj.

Based on UglifyJS by Mihai Bazon.