esbuild-plugin-obfuscator

1.4.0 verified Fri May 01 auth: no javascript

An esbuild plugin that integrates javascript-obfuscator to selectively obfuscate JavaScript files during the build process. Current stable version is 1.4.0, with minor releases on a monthly cadence. Key differentiators: micromatch-based file filtering, optional full output obfuscation, source map support for debugging obfuscated code, and TypeScript type definitions. Alternatives include other esbuild obfuscator plugins like esbuild-obfuscator, but this plugin offers more granular control via filter patterns.

Common errors

error Error: Cannot find module 'esbuild-plugin-obfuscator' ↓

cause Missing package installation or incorrect import path.

fix

Run 'npm install esbuild-plugin-obfuscator --save-dev' and ensure no typos in import.

error TypeError: ObfuscatorPlugin is not a function ↓

cause Using default import instead of named import.

fix

Change 'import ObfuscatorPlugin from ...' to 'import { ObfuscatorPlugin } from ...'

error Error: Cannot find module 'javascript-obfuscator' ↓

cause javascript-obfuscator is not installed as a dependency.

fix

Run 'npm install javascript-obfuscator' (should be auto-installed as peer dependency).

error Error: No files matched the given filter patterns ↓

cause The micromatch patterns in 'filter' do not match any files in the build.

fix

Verify the filter patterns (e.g., ['**/*.js']) and ensure entry points include matching files.

Warnings

gotcha The 'filter' option expects micromatch patterns and defaults to an empty array, meaning no files are obfuscated unless explicitly specified. ↓

fix Provide a filter array with patterns (e.g., ['**/**.js']) to obfuscate all files, or use shouldObfuscateOutput: true for full output obfuscation.

breaking In v1.3.0, source map support was added; enabling source maps in esbuild (sourcemap: true) is required to generate source maps for obfuscated code. ↓

fix Ensure esbuild is configured with sourcemap: true or inline source maps before using source map features.

deprecated Options passed directly to the plugin (like 'compact') are not deprecated but will be overridden if the same key appears in the 'options' object. The plugin merges top-level keys with 'options'. ↓

fix Avoid duplicating obfuscator options: either use top-level keys or the 'options' object, not both.

gotcha The 'ignoreRequireImports' option may cause unexpected behavior if your code uses dynamic require statements; it only prevents obfuscation of require strings that are static. ↓

fix Only use ignoreRequireImports: true if you have static require imports that should not be obfuscated.

gotcha Obfuscating code can significantly increase bundle size and reduce performance; javascript-obfuscator's default settings are heavy. ↓

fix Use minimal obfuscator options (e.g., { compact: true, controlFlowFlattening: false }) for production builds.

Install

npm install esbuild-plugin-obfuscator

yarn add esbuild-plugin-obfuscator

pnpm add esbuild-plugin-obfuscator

Imports

ObfuscatorPlugin

wrong

import ObfuscatorPlugin from 'esbuild-plugin-obfuscator'

correct

import { ObfuscatorPlugin } from 'esbuild-plugin-obfuscator'

Named export, not default. This is the only export.

require('esbuild-plugin-obfuscator')

wrong

const ObfuscatorPlugin = require('esbuild-plugin-obfuscator')

correct

const { ObfuscatorPlugin } = require('esbuild-plugin-obfuscator')

Use destructuring for CommonJS; the module exports a named object.

ObfuscatorPluginOptions
```
import type { ObfuscatorPluginOptions } from 'esbuild-plugin-obfuscator'
```
TypeScript type; available since v1.2.5 for custom options typing.

Quickstart

Demonstrates selective obfuscation of files matching '**/sensitive.js' using micromatch filter, with basic obfuscator options.

import esbuild from 'esbuild';
import { ObfuscatorPlugin } from 'esbuild-plugin-obfuscator';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    ObfuscatorPlugin({
      filter: ['**/sensitive.js'],
      compact: true,
      controlFlowFlattening: true,
    }),
  ],
});
console.log('Build complete with selective obfuscation');