Compressor packs the output into a self-extracting runtime wrapper, so the shipped file is shorter and less readable than the transformed code it contains. It is the one option on this site with a hard deployment prerequisite: the wrapper uses string-to-code execution, so it needs unsafe-eval in your Content Security Policy. Read the CSP section below before enabling it.
What it does
This option stores the final script in a packed form and adds a small bootstrap that rebuilds the code when the file runs. The wrapper adds roughly 1.3 KB of extraction logic, so it is a net loss on small files and a net win on large ones.
Instead of leaving the transformed code visible, the output becomes a compact wrapper around packed data:
(function () {
var packed = "...";
var source = unpack(packed);
execute(source);
})();
Configuration
{
"options": {
"SelfCompression": true,
"CompressionRatio": "Auto",
"SelfCompressionMinSize": 4096
}
}
| Option | Values | Meaning |
|---|
SelfCompression | boolean | Enables the self-extracting wrapper. |
CompressionRatio | Auto, Low, Medium, High, Best | How hard the packer works. Higher ratios cost build time, not runtime. The higher settings are themselves plan-gated: Medium needs Basic, High needs Corporate, and Best needs Enterprise. Auto and Low are not gated beyond this option itself. |
SelfCompressionMinSize | number (bytes) | Files smaller than this are left unpacked, so you do not pay 1.3 KB of bootstrap to save 200 bytes. |
Leave CompressionRatio on Auto unless you have measured a reason not to. Set SelfCompressionMinSize whenever you protect many files of mixed size.
Content Security Policy: this option requires unsafe-eval
The bootstrap rebuilds your code from a string, which means it calls into eval and new Function. Under a strict CSP that omits unsafe-eval, the packed file will not run — you will see a CSP violation and a blank feature, not a JavaScript error you can trace to your own code.
This is worth stating plainly because it is the exception to the general rule. The rest of the engine's transforms — name mangling, string tables and encoding, control-flow flattening, member indirection — emit ordinary code and run fine under a strict CSP with unsafe-eval off. Only two features need the weakening:
If keeping unsafe-eval off matters more than packing — and for most teams it should, since it is one of the highest-value restrictions a CSP can carry — leave both options off and get your size win from transfer compression instead. The full discussion is in does obfuscation break Content Security Policy.
It is probably not the size win you want
Compression here happens inside the file, which is a different thing from compression on the wire. If your server already sends Content-Encoding: gzip or br — and it should — then your users already receive a compressed payload, and packing the file first mostly gives the transport less redundancy to work with.
In exchange for a smaller number on disk you take on: 1.3 KB of bootstrap, an unpack step on every page load before your code runs, and the CSP requirement above. Measure the gzipped size both ways before concluding this option helps. There are real cases where it does — a file served without transport compression, an embedded or offline context, a single-file distribution — but "smaller bundle" on a normally configured web server is usually not one of them.
Interaction with other options
- Code Formatter is ignored. Formatted output is pointless inside a packed wrapper, so
WriteFormats has no effect when this option is on.
- Encode Strings overlaps. Packing already hides literals from a plain text search, so the two do not add up. Enabling both is harmless but do not count it twice.
- Verify strict-mode behavior. A leading
"use strict" is a directive only when it is the first statement in its scope, and packing rewrites the top of the file. If your code depends on strict mode, assert that dependence in a test that runs against packed output rather than assuming it survives — see does obfuscation preserve use strict for why this class of bug is silent.
- Debugging gets harder. Stack traces point into the reconstructed code, so line numbers do not correspond to anything you can open. Use unpacked builds for investigation, and keep the identifier map for symbolication.
Use it deliberately: Compressor is useful when you want a harder-to-read single-file result and you control the environment it runs in. It is the wrong default if your pipeline already applies transport compression, if you run a strict CSP, or if you want the lightest possible runtime behavior.
Frequently asked questions
Does this option make the download smaller for users?
Usually not, and that is the most common misunderstanding about it. Compression here happens inside the file, while your server almost certainly already applies transport compression to the response. Packing the file first mostly removes the redundancy the transport compressor would have exploited, so the number on disk falls while the number on the wire moves very little. Measure the compressed size both ways before concluding it helped. The cases where it genuinely wins are files served without transport compression, embedded or offline contexts, and single-file distribution.
Why does the packed output need unsafe-eval in our policy?
Because the wrapper rebuilds your code from a string at load time, which means it goes through the string-to-code path. A policy that omits that permission will refuse to run the packed file, and the symptom is a policy violation and a feature that silently does nothing rather than an error you can trace back to your own code. This is the one option on the site with a hard deployment prerequisite, which is why it is worth checking your policy before enabling it rather than after.
Which other options have the same requirement?
Exactly one, and knowing the list is short is the useful part. Apart from this option, only the eval-based code transposition variant needs that permission. Every other transform in the engine emits ordinary code and runs correctly under a strict policy with the permission switched off, including name mangling, the string table and encoding passes, control-flow flattening and member indirection. If keeping that restriction in place matters to you, and for most teams it should, leaving both of those options off costs you nothing else.
What does the compression ratio setting actually control?
How hard the packer works, and the cost lands on build time rather than on run time. The available levels run from automatic through low, medium, high and best. The upper levels carry plan requirements of their own: medium needs the entry paid tier, high needs the middle tier and best needs the top tier, while automatic and low are not gated beyond the option itself. Leaving it on automatic is the right default unless you have measured a reason to change it.
What is the minimum size setting for?
Avoiding a bad trade on small files. The wrapper adds roughly one and a third kilobytes of extraction logic, so packing a two hundred byte file makes it substantially larger. The minimum size setting tells the engine to leave anything below the threshold unpacked, which matters whenever you protect many files of mixed size in one run and do not want to inspect each result individually.
What gets harder after enabling it?
Three things worth planning for. Stack traces point into reconstructed code, so line numbers no longer correspond to anything you can open, which makes production debugging materially worse unless you keep the identifier map and use unpacked builds for investigation. Code formatting has no effect, because readable formatting inside a packed wrapper is pointless. And because packing rewrites the top of the file, a leading strict-mode directive is only a directive when it is the first statement in its scope, so any dependence on strict mode should be asserted by a test that runs against packed output rather than assumed.
When is this genuinely the right option to enable?
When you want a harder-to-read single-file result and you control the environment it runs in. That combination is real: a distributed single file, an embedded runtime, an offline context, or a delivery path with no transport compression. It is the wrong default when your pipeline already compresses in transit, when you run a strict content policy, or when you want the lightest possible behaviour at load time.