Documentation

Guides for protecting production JavaScript

Reference guides for release workflows, command-line usage, cross-file protections, and the desktop app.

Build And Release Workflows Download Desktop
Inside The Docs

Practical guides, not placeholder pages.

How-to guides Start with release sequencing and command-line usage, then move into feature-specific references.
Advanced protection Browse cross-file controls like Replace Globals and Protect Members when a build spans multiple scripts.

Compatibility and Release Validation

  • npm CLI, desktop, API, framework build workflows

Use this page when a protected build must stay compatible with frameworks, customer integrations, browser entry points, and release-time debugging rules. The safest pattern is build first, protect second, then test the protected output as its own release candidate.

Start with the stable output

Protect the JavaScript emitted by Vite, Webpack, Rollup, esbuild, Browserify, or your desktop project workflow. Do not place obfuscation inside a compiler stage that still owns JSX, TypeScript, framework templates, or tree-shaking logic.

Good release target
Generated JavaScript chunks, bundle outputs, and inline script blocks that are already final JavaScript.		 Avoid protecting directly
Raw .ts, .tsx, .jsx, Vue single-file components, or framework template source.
Protect separately
Write to a folder such as dist-protected so testing and rollback compare protected artifacts cleanly.		 Skip by default
Vendor bundles, polyfills, framework runtime files, and stale source maps unless the release owner has reviewed them explicitly.

Preserve public names and integration contracts

Any function, class, method, or global name called by code outside the protected bundle must stay stable. Use reservedNames, the Variable Exclusion List, or desktop project exclusions before enabling stronger cross-file transforms.

  1. Preserve names used by server-rendered markup, HTML attributes, analytics tags, widget hosts, or embedded checkout scripts.
  2. Preserve framework entry points, externally imported modules, and public SDK methods.
  3. Protect shared bundles together when they rely on renamed globals, members, or object declarations.
  4. Keep one reviewed exclusion list in version control so release behavior does not drift between contributors.

Debugging and source-map policy

Protected releases should be debugged on the protected output, not by assuming the unprotected build behaves the same way. Source maps can reveal original source, so the hosted workflow excludes them from protected release artifacts by default.

Recommended
Run smoke tests, browser checks, and error monitoring against the protected build folder.		 Use care
Keep source maps and symbol notes private if your release process requires them for internal troubleshooting.
Review stack traces
Confirm error monitoring, logging, and crash reports still surface enough context after protection.		 Keep contracts documented
Record excluded names, domain locks, and date locks in release notes so operations teams understand intentional runtime behavior.

Browser and framework checks

Before deployment, test the protected build in the browsers and flows that matter most to the release. Focus on the surfaces most likely to break after renaming or code movement.

  1. Load the protected build in every supported browser family and run key logged-in and logged-out paths.
  2. Check dynamic imports, lazy chunks, route transitions, hydration, and any scripts injected by a CMS or server template.
  3. Confirm feature flags, localization files, and runtime configuration still bind to the expected names.
  4. Check any externally loaded widget, customer embed, or partner integration that calls your JavaScript by name.

CI release gate

The goal is to fail before deployment when config, compatibility, or runtime expectations drift. Use a repeatable gate in CI and keep the same structure for local release rehearsals.

npx jso-protector --release-check --strict --json
npm run build
npx jso-protector --config jso.config.json
npm run smoke:protected
npm run browser-matrix
deploy ./dist-protected

Add --check-api when the build should also verify endpoint health with a tiny generated sample before the full protection step.

If protected output breaks

Reduce uncertainty before changing many options at once. The fastest path is usually to compare a passing lower-friction preset against the failing release profile.

  1. Confirm the failing symbol should have been excluded, reserved, or kept public.
  2. Skip vendor, polyfill, runtime bootstrap, or generated manifest files that do not need protection.
  3. Compare standard, balanced, and the current release preset to isolate the transform that introduced the break.
  4. Move the release into a desktop project when mixed HTML or embedded-script processing needs visual review.