Gulp JavaScript Obfuscator

Common errors

• Error in plugin "gulp-javascript-obfuscator" Message: The number of constructor arguments in the derived class t must be >= than the number of constructor arguments of its base class.

  cause Incompatibility between `javascript-obfuscator`'s internal dependencies and specific Node.js versions (e.g., Node.js 13.6+).
  fix Downgrade your Node.js version to a compatible LTS release (e.g., Node.js 12.x) or check for newer versions of `gulp-javascript-obfuscator` and `javascript-obfuscator` that support your Node.js version.

• SyntaxError: Unexpected token ... (related to spread syntax in `chalk` or other dependencies)

  cause Older Node.js environments or misconfigured transpilation pipelines struggling with modern JavaScript syntax used by `javascript-obfuscator` or its sub-dependencies.
  fix Ensure your Node.js version supports the syntax used by the library and its dependencies, or use a transpiler like Babel if targeting older environments. Check `javascript-obfuscator`'s compatibility matrix.

• TypeError: javascriptObfuscator is not a function

  cause The `gulp-javascript-obfuscator` module was not correctly `require`d, or the variable name does not match the imported symbol.
  fix Verify that `const javascriptObfuscator = require('gulp-javascript-obfuscator');` is correctly placed and that `javascriptObfuscator` is used as a function in the `.pipe()` chain.

• Error: Cannot find module 'vinyl-sourcemaps-apply'

  cause A dependency issue where `gulp-sourcemaps` or `gulp-javascript-obfuscator` cannot find a required sub-dependency for sourcemap processing.
  fix Run `npm install` or `yarn install` again to ensure all transitive dependencies are correctly installed. This can sometimes be resolved by clearing the npm cache (`npm cache clean --force`).

Warnings

• breaking When using `gulp-sourcemaps` for source map generation, the `sourceMap` option within `javascript-obfuscator` configurations MUST NOT be set. The plugin handles source map integration automatically, and explicitly setting `sourceMap: true` will cause conflicts or incorrect behavior.
  Fix: Remove `sourceMap` from the options object passed to `javascriptObfuscator()`. Ensure `sourcemaps.init()` is called before and `sourcemaps.write()` after the obfuscator in the Gulp pipeline.
• deprecated The method of generating source maps by directly setting `sourceMap: true` in the `javascript-obfuscator` options (without `gulp-sourcemaps`) is deprecated. This older approach generates a `.map` file directly into the Gulp stream but is not recommended for future use and may be removed in later versions.
  Fix: Migrate to using `gulp-sourcemaps` for robust and compatible source map generation. Follow the `gulp-sourcemaps` integration pattern: `pipe(sourcemaps.init()).pipe(javascriptObfuscator()).pipe(sourcemaps.write())`.
• gotcha Older Node.js versions (e.g., 13.6 and above) have been reported to cause 'Spread Syntax error' or 'The number of constructor arguments in the derived class must be >= than the number of constructor arguments of its base class' when using `gulp-javascript-obfuscator` due to incompatibilities with underlying dependencies.
  Fix: If encountering these errors, consider downgrading to a compatible Node.js LTS version (e.g., Node.js 12.x) or updating `gulp-javascript-obfuscator` and its core dependency `javascript-obfuscator` to their latest versions if a fix has been released for your Node.js version.

Install

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

Imports

• javascriptObfuscator
  wrong:

  import javascriptObfuscator from 'gulp-javascript-obfuscator';

  correct:

  const javascriptObfuscator = require('gulp-javascript-obfuscator');

  This is a CommonJS module, primarily used in Gulpfiles which are typically CommonJS. Direct ESM `import` will not work.
• gulp
  wrong:

  import gulp from 'gulp';

  correct:

  const gulp = require('gulp');

  Gulpfiles are traditionally CommonJS modules. `import` syntax is not typically supported without additional transpilation.
• sourcemaps
  wrong:

  import sourcemaps from 'gulp-sourcemaps';

  correct:

  const sourcemaps = require('gulp-sourcemaps');

  Like other Gulp plugins, `gulp-sourcemaps` is imported using CommonJS `require` in a Gulpfile.

Quickstart

This quickstart demonstrates how to set up a Gulp task to obfuscate JavaScript files, incorporating Babel for transpilation and `gulp-sourcemaps` for generating debug-friendly sourcemaps alongside the obfuscated output.

const gulp = require('gulp');
const javascriptObfuscator = require('gulp-javascript-obfuscator');
const sourcemaps = require('gulp-sourcemaps');
const babel = require('@babel/core'); // Optional: for pre-processing JS
const babelPresetEnv = require('@babel/preset-env'); // Optional: for Babel preset

gulp.task('obfuscate-js', () => {
  return gulp.src('src/**/*.js')
    .pipe(sourcemaps.init()) // Initialize sourcemaps before any transformations
    .pipe(babel({
      presets: [babelPresetEnv]
    })) // Optional: Transpile modern JS to a compatible version
    .pipe(javascriptObfuscator({
      compact: true, // Example option: compact the obfuscated code
      // Other javascript-obfuscator options can go here
      // IMPORTANT: Do NOT set `sourceMap: true` here when using gulp-sourcemaps
    }))
    .pipe(sourcemaps.write('.')) // Write sourcemaps to the same directory as output
    .pipe(gulp.dest('dist')); // Output obfuscated and sourcemap files to 'dist'
});

// To run this task: npx gulp obfuscate-js