JavaScript Obfuscator - Introduction and key concepts

Table of contents

Key facts about JavaScript Obfuscator

  • It never overwrites input files.
  • It has both GUI and command line interfaces. GUI uses command line interface under the hood, but GUI adds some handy tools, so GUI interface is more powerfull and feature-rich and is more recommended to use.

    It's really greatly recommended to use GUI interface to set up the project. Later you can export scripts (or .bat files for Windows) that allow you to build/rebuild/clean your project from command line - they are called buildscripts.

    And if you insist on never using GUI interface (it's very bad idea!) you can still generate command line using GUI on your computer (go to Tools ⇒ Command line builder) or online command line builder available on our site.

  • Trial version can perform only one kind of transformation for symbol names - by prepending string ReplacementFor_ to them. This does not limit your ability to evaluate JavaScript Obfuscator in any way! The trial version does allow you to fully evaluate JavaScript Obfuscator and prepare your project for obfuscation using only trial edition.

    Just imagine that instead of ReplacmentFor_someFunction you'll get z78a4b2e. Those symbols that got prefix with trial version will become something unreadable when protected by non-trial. It's easier to prepare project for obfuscation using this kind of replacement (when some prefix is prepended), so it's called a debug mode. Using debug mode is recommended when using non-trial version of the product too! - as it allows to understand what's going on much easier (you'll get errors looking like "unknown symbol ReplacementFor_someFunction" instead of "unknown symbol z72a63be9f" - the former is much more readable when debugging!).

    Once you created a project, prepared it for protection using trial, you can purchase non-trial, just open that project in non-trial edition, click Build ⇒ Rebuild all and you'll get your project fully protected. So you won't loose any time spent evaluating trial edition.

  • Default settings and values of parameters are safe and reasonable.
  • Obfuscation of the project is not as quick as zipping the folder with source code - you have to confiure your project (by listing names that should not be modified, called exceptions) and even modify your code a little in case you use eval() in your code . So be ready to spend from hours to days before you get protected version of your code that works correctly after obfuscation.

Key concept: exceptions - names of symbols that should not be modified

The purpose of JavaScript Obfuscator is to replace symbols with meaningless names. Apparently, not all symbols can be changed without introducing errors. For example, names of core API (e.g. Math.Pi or Date) or DOM API (e.g. document, location) can not be changed. Names of such symbols should be added to the list of exceptions - so obfuscator does not change them adding symbols to exceptions .

Symbols defined in 3rd-party libraries

If your code calls some functions from 3rd-party libraries that your code loads from remote site using <script> attribute or you are not allowed to modify , you have to list all symbols that you use from those libraries as exceptions adding symbols to exceptions .

JavaScript Obfuscator ships with a lot of tools that help generating exceptions for 3rd-party libraries extacting list of symbols . But it's greatly recommended to add all 3rd-party libraries to your project and obfuscate them together with your code. This way you won't have to bother generating exceptions for them. Even if they are already minified - it's not a problem!

Exporting symbols to 3rd parties

If your code is in fact a library that you sell or distribute, then you have to list as exceptions all symbols defining its API adding symbols to exceptions . Use tools shipped with JavaScript Obfuscator to generate exceptions for API of your library extacting list of symbols

Handling symbols defined by HTML markup

If your client-side code uses old-style way of accessing nodes by their IDs via document.all (e.g. document.all.callToAction) or form elements by their names using document.forms[] array (e.g. document.forms[1].radio_name), then names or IDs of those elements and form fields have to be listed as exceptions too. JavaScript Obfuscator includes tools to generate exceptions for these cases too generating exceptions for element names and IDs

Dealing with names of symbols in strings

Sometimes, your code refers to names of functions or variables inside the strings, e.g. in strings passed to eval() or setTimeout() functions. What to do in such case:

If the name of the symbol inside the string is computed at runtime
(e.g. entered by the user , or read from some attribute of some DOM node), then the only option you have is to list all possible names of symbols that can be used this way in your code in the list of exceptions adding symbols to exceptions .

If the name of the symbol is a constant string
you have these options:
  • put that symbol to the list of exceptions to prevent it from being modified adding symbols to exceptions .
  • List that symbol as "quoted symbol name". In this case JavaScript Obfuscator will replace every string whose value is equal to the symbol name, with a string equal to mangled symbol name. Strings that include some other characters around symbol name won't be changed. Register "quoted symbol name" in Symbols ⇒ Edit strings that contains symbol names if using GUI, or put them, one symbol per line, to a text file and pass its name after --quoted-symbol-names command line option if using command line interface.
  • wrap that name in the call to OBJNAME function (enclosing the name of the symbol in single quotes; double quotes will not work; no spaces between parentheses and quoted symbol name are allowed)
        var varname = "myvar";
        eval(varname + '= 23;");
        var varname = OBJNAME('myvar');
        eval(varname + ' = 23;');

    For this to work, add the following lines to the begining of your files (or make sure that these definitions are visible to each of your files):
    function OBJNAME(n) { '';return n; }

GUI has special tool to help with this - it lists all symbols found inside strings, in Symbols ⇒ View strings encountered in code. Most probably you should copy list of such symbols to Symbols ⇒ Edit strings that contains symbol names, or to the list of exceptions (Symbols ⇒ Edit user-specified exceptions), or alter your code by wrapping string constants with those symbols in call to OBJNAME().

Steps for obfuscating the project with JavaScript Obfuscator

Step 1: add OBJNAME to your code

Alter all places where your code refers to names of symbols inside string constants, by wrapping names of symbols into a call of OBJNAME function, as explained above.

Then test that after these changes your unobfuscated code works same as your original code.

Step 2: collect set of exceptions for your code

A lot of tools for this are shipped with JavaScript Obfuscator extacting list of symbols

Step 3: process your code using lite protection and test it

With lite protection, names of symbols that are to be made unreadable, will just get ReplacementFor_ prefix. This will result in error messages looking like "Undefined function ReplacementFor_SomeFunctionName" when you'll run your code - it will clearly indicate that symbol SomeFunctionName should be added to the list of exceptions (see more on what exceptions are here).

Proceed to next step only if your protected code works fine.

Step 4: process your code using non-lite protection and test it

After switching protection mode to non-lite, your code should work exactly as when protected by lite protection. Note that trial version of JavaScript Obfuscator can perform only one kind of transformation for symbol names - by prepending prefix ReplacementFor_ to them. This does not limit your ability to evaluate JavaScript Obfuscator in any way as mangling integers and strings in non-lite mode is the same for both trial and non-trial, so once you tested your code protected with trial in non-lite mode, you will need only minimal testing of code once upgrading trial into non-trial of JavaScript Obfuscator.