Grunt JavaScript Obfuscator

Common errors

• Warning: Task "javascript_obfuscator" not found. Use --force to continue.

  cause The Grunt plugin `grunt-javascript-obfuscator` has not been loaded in your Gruntfile.
  fix Add `grunt.loadNpmTasks('grunt-javascript-obfuscator');` to your `Gruntfile.js`.

• Fatal error: Peer dependency 'javascript-obfuscator@>=0.7.2' not met. Please install 'javascript-obfuscator@>=0.7.2' manually.

  cause The required peer dependency `javascript-obfuscator` is not installed or its version does not meet the specified requirement.
  fix Run `npm install javascript-obfuscator --save-dev` to install the core obfuscator library alongside the Grunt plugin.

• Warning: grunt-javascript-obfuscator: `files` or `src` is required.

  cause The `javascript_obfuscator` task is missing the `files` or `src` configuration to specify which JavaScript files should be obfuscated.
  fix Configure your task target with either a `files` object (e.g., `files: { 'dest.js': ['src1.js', 'src2.js'] }`) or a `src` array (e.g., `src: ['src/*.js']`).

Warnings

• gotcha The package's peer dependency for Grunt (`>=0.4.5`) is very old. While it might work with newer Grunt versions, compatibility issues with modern Grunt features or Node.js versions are possible.
  Fix: Ensure your Grunt CLI and Grunt library versions are compatible with older plugins. Consider testing thoroughly or migrating to a more actively maintained build tool if encountering issues.
• breaking Options passed to `grunt-javascript-obfuscator` are directly forwarded to `javascript-obfuscator`. The underlying `javascript-obfuscator` library has undergone many changes and additions since this plugin's last release (v1.2.0 in 2019). Options might have changed names, been deprecated, or introduced new behaviors.
  Fix: Always consult the latest documentation for `javascript-obfuscator` to ensure that the options you are using are current and behave as expected. Test your obfuscated code thoroughly with each configuration change.
• gotcha JavaScript obfuscation, while increasing difficulty, does not provide encryption or absolute security for your code. It primarily deters casual inspection and makes reverse-engineering more complex.
  Fix: Do not rely on obfuscation as a sole security measure for sensitive logic or data. Combine it with server-side validation, API key protection, and other security best practices where true security is required.
• gotcha Source maps were introduced in v1.2.0, but generating source maps for highly obfuscated code can still be challenging. Debugging obfuscated code, even with source maps, is significantly harder than debugging original code.
  Fix: Ensure you are on v1.2.0 or higher to use source map generation. Always generate and retain original source code for debugging purposes and only deploy obfuscated versions to production.

Install

• npm install grunt-javascript-obfuscator npm
• yarn add grunt-javascript-obfuscator yarn
• pnpm add grunt-javascript-obfuscator pnpm

Imports

• grunt.loadNpmTasks
  wrong:

  import { javascriptObfuscator } from 'grunt-javascript-obfuscator';

  correct:

  grunt.loadNpmTasks('grunt-javascript-obfuscator');

  Grunt plugins are loaded via `loadNpmTasks` in the Gruntfile, not traditional ES modules or CommonJS imports for the task itself.
• javascript_obfuscator task configuration
  wrong:

  grunt.registerTask('obfuscate', ['javascript_obfuscator']);

  correct:

  grunt.initConfig({ javascript_obfuscator: { ... } });

  The task is configured within `grunt.initConfig` under the `javascript_obfuscator` key. `registerTask` is for creating aliases or combining tasks.
• Task Options

  options: { debugProtection: true, debugProtectionInterval: true }

  Options for the obfuscation process are passed directly to the underlying `javascript-obfuscator` library. Refer to `javascript-obfuscator`'s documentation for available options.

Quickstart

This example demonstrates how to set up `grunt-javascript-obfuscator` to obfuscate a single JavaScript file, `src/input.js`, into `dist/obfuscated.js` using a comprehensive set of obfuscation options and source map generation. It includes the necessary `npm install` command, a sample `input.js`, and a `Gruntfile.js` for configuration.

npm install grunt grunt-cli grunt-javascript-obfuscator javascript-obfuscator --save-dev

// src/input.js
(function(){
    var sensitiveData = 'this is a secret value';
    function performCalculation(a, b) {
        return a * b;
    }
    console.log("Result: ", performCalculation(5, 10));
    if (process.env.NODE_ENV === 'production') {
        console.log(sensitiveData);
    }
})();

// Gruntfile.js
module.exports = function(grunt) {
  grunt.initConfig({
    javascript_obfuscator: {
      options: {
        compact: true,
        controlFlowFlattening: true,
        deadCodeInjection: true,
        debugProtection: true,
        debugProtectionInterval: true,
        disableConsoleOutput: true,
        identifierNamesGenerator: 'hexadecimal',
        log: false,
        renameProperties: false,
        selfDefending: true,
        simplify: true,
        splitStrings: true,
        stringArray: true,
        stringArrayEncoding: ['base64'],
        stringArrayThreshold: 0.75,
        transformObjectKeys: true,
        unicodeEscapeSequence: false,
        sourceMap: true // Added in v1.2.0
      },
      dist: {
        files: {
          'dist/obfuscated.js': ['src/input.js']
        }
      }
    }
  });

  grunt.loadNpmTasks('grunt-javascript-obfuscator');

  grunt.registerTask('default', ['javascript_obfuscator']);
};