Inline Protection Directives

Two directive styles

Pick the style that matches whether most of the file should be protected (skip a few regions) or most of the file should be left alone (protect a few regions).

Both markers also accept the block-comment form, e.g. /* javascript-obfuscator:disable */, for contexts where a line comment is awkward.

Skip a region

Use when most of the file should be protected but a small region must ship readable — a license header, a public API surface other code reflects on by name, or a third-party snippet you are not allowed to modify.

// app.js
export function chargeCard(token) {
  // ... protected business logic ...
}

// javascript-obfuscator:disable
// This block is shipped exactly as written.
window.MyWidgetPublicAPI = {
  version: "3.2.0",
  mount: mountWidget,
  unmount: unmountWidget
};
// javascript-obfuscator:enable

export function settle(order) {
  // ... protected again ...
}

Run it:

npx jso-protector --config jso.config.json --honor-conditional-comments

Or set it once in jso.config.json:

{ "honorConditionalComments": true }

Protect only a region

Use when most of the file is framework glue or generated boilerplate and only a small core deserves protection — a license check, a fraud rule, a proprietary algorithm.

// licensing.js
import { readClock } from "./platform";   // left readable

// javascript-obfuscator:protect-begin
function verifyLicense(sig, payload) {
  // ... the only part worth protecting ...
}
// javascript-obfuscator:protect-end

export { verifyLicense };               // left readable

npx jso-protector --config jso.config.json --protect-marked-comments

{ "protectMarkedComments": true }

Rules the CLI enforces

• One style per file. Mixing disable/enable with protect-begin/protect-end in the same file fails with a clear error. Pick the one that means less marking.
• Markers must be balanced. An unmatched or nested region fails before any source leaves your machine — the CLI reports the file and line so you can fix it.
• Fail-safe by default. If a file contains markers but you did not pass the matching flag, the CLI stops and points at the first marker rather than silently ignoring your intent. This prevents a marked region from being protected (or shipped) by accident.
• Verbatim means verbatim. Skipped regions are spliced back byte-for-byte after protection, so identifier names other code depends on stay stable.

How it differs from VariableExclusion and named sets

Three tools, three scopes — they compose:

• Inline directives (this page) act on regions of a file and live in the source next to the code they affect.
• VariableExclusion keeps specific identifier names un-renamed across the whole build — use it when a global name must survive, not when a whole region must.
• Named configuration sets apply a different preset and options to different files by glob — e.g. maximum protection for src/checkout/**, standard for marketing pages.

A common layering: a named set selects the preset for the checkout folder, and inline directives inside one checkout file skip a public API object that other modules call by name.

Frequently asked questions

What are inline protection directives for?

They let you control protection per region directly in the source, instead of splitting a file in two or maintaining a separate exclusion list somewhere else. The command line tool reads specially formatted comments and either skips the marked region or protects only the marked region. The advantage is that the decision lives next to the code it applies to, so it survives refactoring in a way an external list of names does not.

What is the difference between the two styles?

They are opposites, and you pick based on which way round your file is. The skip style protects everything except the marked region, which suits a file where nearly all the code should be transformed and a small part must be left verbatim. The protect-only style transforms nothing except the marked region, which suits a file that is mostly untouchable with one sensitive section in it. Use one style per file rather than mixing them.

Do I need to enable anything for the markers to be honoured?

Yes, and this is the step most often missed. Each style has its own switch, and without it the markers are not treated as instructions. The skip style is enabled by the option that honours conditional comments, and the protect-only style by the option that protects marked comments. A file full of correct markers with neither option enabled is simply a file with some comments in it.

Can I write the markers as block comments?

Yes. Both markers also accept the block-comment form, which is useful in contexts where a line comment would not survive or would run to the end of a line you need. The marker text is the same in either form; only the comment syntax differs. Pick whichever reads better in the surrounding code.

How is this different from the exclusion list?

They operate on different things. The exclusion list names identifiers that must never be renamed, wherever they appear, and it is the right tool when something outside your file refers to a name by its exact text. Directives mark regions of code that should be skipped or protected as a whole, regardless of what identifiers are in them. Use the exclusion list for a name that is part of a contract, and a directive for a block of code that must not be transformed at all.

What happens if my markers are unbalanced?

The tool enforces the pairing rather than guessing, which is deliberate: silently protecting a region you meant to skip is the kind of failure that shows up much later and is hard to attribute. Keep the opening and closing markers in the same file, do not nest them, and treat a complaint about an unmatched marker as a real defect in the source rather than something to work around.