Webpack Obfuscator Plugin and Loader

Common errors

• TypeError: WebpackObfuscator is not a constructor

  cause Incorrect import statement (e.g., using named import for a default export) or trying to `require` a pure ESM package.
  fix For CommonJS, `const WebpackObfuscator = require('webpack-obfuscator');` is shown in the README. For ESM, use `import WebpackObfuscator from 'webpack-obfuscator';`

• Error: Cannot find module 'javascript-obfuscator'

  cause The `javascript-obfuscator` package, a peer dependency, is not installed.
  fix Install the peer dependency: `npm install --save-dev javascript-obfuscator`.

• Error: The 'options' property is only allowed for 'plugins' with a 'tap' hook

  cause Attempting to pass loader options directly to the `WebpackObfuscator` plugin constructor without nesting them under `options` for the loader itself, or mistaking plugin usage for loader usage.
  fix When using `WebpackObfuscator.loader`, options should be nested under `options` in the `use` object: `{ use: { loader: WebpackObfuscator.loader, options: { rotateStringArray: true } } }`.

• Webpack compilation fails or code is not obfuscated as expected (Webpack 4 user)

  cause Using `webpack-obfuscator` v3.x with Webpack 4, which is incompatible.
  fix Downgrade `webpack-obfuscator` to a 2.x version (e.g., `npm install webpack-obfuscator@^2.0.0 --save-dev`) or upgrade your project to Webpack 5.

Warnings

• breaking Version 3.0.0 and higher of `webpack-obfuscator` are only compatible with Webpack 5 and above. Older Webpack versions (e.g., Webpack 4) require `webpack-obfuscator` version 2.x.
  Fix: Upgrade to Webpack 5 or higher, or downgrade `webpack-obfuscator` to a 2.x release if tied to Webpack 4.
• breaking Starting with version 3.0.0, `javascript-obfuscator` is a peer dependency and must be installed explicitly alongside `webpack-obfuscator`. Previously, it was a direct dependency.
  Fix: Ensure `javascript-obfuscator` is installed: `npm install --save-dev javascript-obfuscator`.
• gotcha Using the Pro API for cloud-based obfuscation requires `javascript-obfuscator` version 5.0.0 or higher. Ensure your `javascript-obfuscator` peer dependency meets this requirement if you intend to use Pro API features.
  Fix: Verify `javascript-obfuscator` version in `package.json` and update if necessary (`npm install javascript-obfuscator@latest`).
• gotcha When using the loader, it's recommended to add `enforce: 'post'` to your webpack rule. This ensures the obfuscator loader runs after all other normal loaders, preventing potential conflicts or issues where other loaders might interfere with the obfuscation process.
  Fix: Add `enforce: 'post'` to the loader rule in your webpack configuration: `{ test: /\.js$/, enforce: 'post', use: { loader: WebpackObfuscator.loader, ... } }`.
• gotcha The `excludes` option for the plugin takes bundle names (output file names), not source file names. When using `[name].js` in webpack's output, these are the names to exclude. For the loader, `exclude` takes source file paths.
  Fix: For the plugin, ensure `excludes` array matches your compiled bundle names (e.g., `['my-bundle.js']`). For the loader, use `path.resolve(__dirname, 'src/excluded-file.js')`.

Install

• npm install webpack-obfuscator npm
• yarn add webpack-obfuscator yarn
• pnpm add webpack-obfuscator pnpm

Imports

• WebpackObfuscator
  wrong:

  const WebpackObfuscator = require('webpack-obfuscator');

  correct:

  import WebpackObfuscator from 'webpack-obfuscator';

  While the README shows `require()`, for modern Webpack configurations and TypeScript, ESM `import` is preferred. The package ships with types.
• WebpackObfuscator.loader
  wrong:

  import { loader } from 'webpack-obfuscator';
  // The loader is a static property on the default export.

  correct:

  import WebpackObfuscator from 'webpack-obfuscator';
  // then use WebpackObfuscator.loader

  The loader reference is a property of the default export, not a named export.
• WebpackObfuscator Plugin Usage (TypeScript)

  import WebpackObfuscator from 'webpack-obfuscator';
  
  const config: Configuration = {
    // ...
    plugins: [
      new WebpackObfuscator({ rotateStringArray: true }, ['excluded_bundle_name.js'])
    ]
  };

  When using TypeScript, import `WebpackObfuscator` as a default import. Webpack configuration types can be imported from `webpack`.

Quickstart

Demonstrates a basic Webpack configuration applying `webpack-obfuscator` as both a plugin (for global bundle obfuscation with exclusions) and a loader (for individual file obfuscation before other loaders, using `enforce: 'post'`).

const path = require('path');
const WebpackObfuscator = require('webpack-obfuscator');

module.exports = {
    mode: 'production',
    entry: {
        'main': './src/index.js'
    },
    output: {
        path: path.resolve(__dirname, 'dist'),
        filename: '[name].js'
    },
    plugins: [
        new WebpackObfuscator({
            rotateStringArray: true,
            stringArrayThreshold: 0.75
        }, ['main.js'])
    ],
    module: {
        rules: [
            {
                test: /\.js$/,
                exclude: /node_modules/,
                enforce: 'post',
                use: {
                    loader: WebpackObfuscator.loader,
                    options: {
                        compact: true
                    }
                }
            }
        ]
    }
};