Overview

Applying the same set of transformations to a JavaScript application or source file may have an undesired impact on performance, or sometimes, an unsatisfactory obfuscation potency in a specific part of the source code. So, a feature that allows the user to change the behavior of Jscrambler in specific parts of the code is extremely useful to mitigate those problems. Such a feature exists and it is called Code Annotations.

Code Annotations are JavaScript comments (same syntax as JSDoc) that change Jscrambler's behavior in specific parts of your source code. Preceding a line of code with a Code Annotation tells Jscrambler that new protection directives may exist for that same line of code. For instance, preceding a statement with a Code Annotation affects that statement only, where preceding a code block affects the whole block including all inner statements and blocks (i.e. inner blocks inherit their parent's Code Annotations directives).

Jscrambler Code Annotation always begin with the tag @jscrambler followed by a directive or the global modifier. Here is a basic example of how a Code Annotation looks like:

/**
 * @jscrambler define selfDefending {threshold: 512} as sd1
 * @jscrambler enable functionOutlining, sd1
 */
function foo () {}

This configures Jscrambler to perform Function Outlining in function foo body and add Self Defending capabilities to the function foo only if the size of the function is at least 512 chars long.

Currently, there are 5 directives available in Code Annotations:

Directive Description
enable Enable transformations or transformations aliases
define Define a transformation alias with custom options
disable Disable transformations, targets, or transformations aliases
order Reorder and repeat transformations and aliases
target Enable all transformations available for a set of JavaScript targets (e.g. strings, numbers, functions)

To disable all the transformations except Whitespace Removal and Identifiers Renaming, use the wildcard * together with the disable directive. Add this before the beginning of a block to disable them inside that block, or include the global directive to disable them for the entire file. This is what it will look like:

Disabling for a block:

// @jscrambler define identifiersRenaming {includeList: [var1, var2]} as ir
// @jscrambler enable ir

// This function will be targeted

function foo(){/*code...*/}

// This function will not be targeted

// @jscrambler disable *
function bar(){/*code...*/}

Disabling for a file:

// @jscrambler global disable *

// Both functions will not be targeted

function foo () {/*code...*/}
function bar () {/*code...*/}

If using annotations as comments is not an option, because your build process removes them from the code before it is subjected to the protection process, there is the possibility of using String Annotations.

Notes

  • Jscrambler Annotations do not work when placed before an Import Statement
// @jscrambler enable stringSplitting
import fs from 'fs';