mangle.json

It's standard practice for minifiers to compress function and variable names, since doing so is mostly assumed to be transparent to the developer. Microbundle makes it easy to extend this approach to property names as well, which can have a large impact on size for projects containing many objects or classes. This process is referred to as "property mangling" and is implemented using Terser, just like standard variable mangling.

Enabling Property Mangling

To enable property mangling, you must specify a regular expression pattern that dictates which properties should be compressed to shorter names. This can be done in a mangle.json configuration file, or in a "mangle" key in your package.json. Both usages follow the same object format:

{
  "mangle": {
    "properties": {
      "regex": "^_"
    }
  }
}

In the above example, we are instructing Microbundle to shorten any properties matching the pattern ^_, which would be any property beginning with an underscore. This is the most common usage, as underscore-prefixed properties are often used to emulate "private" properties in JavaScript.

Custom Property Name Mappings

Mangled property names become single-character names by default, however these can be overridden in the mangle configuration. The property name mappings are stored in mangle.json alongside the configuration for which names should be mangled:

{
  "mangle": {
    "regex": "^_"
  },
  "props": {
    "props": {
      "$_somePrivateProperty": "__p",
      "$_backingInstance": "__b"
    }
  }
}

Overriding the property name mappings is generally a good idea, since it ensures property names are deterministic: every build will shorten properties to the same names you define.

To get started, first add a mangle.json to your project, then run your microbundle build command. This will mangle all property names matching your regex, and update your mangle.json file with the generated single-letter mangled property names. From there, you can change the name values and re-save the file, which will be respected in all subsequent builds.

Reserved Property Names

In rare cases, a codebase may need to preserve the source names for properties that match the mangle pattern. To address this, a list of property names to keep un-mangled can be supplied using the mangle.reserved key. Here's an example that mangles all properties with a leading underscore except __webpack_public_path__:

{
  "mangle": {
    "regex": "^_",
    "reserved": [
      "__webpack_public_path__"
    ]
  }
}

For mangle.json implementors

If you're building a tool and would like to use the same mangle.json format as Microbundle, there are a few useful bits of information you should know:

1. The JSON is parsed into an object that gets mutated in-place by Terser, then it is saved back to disk.
2. The official structure is mangle.properties.regex, however mangle.regex is supported as a shortform. This is also true for mangle.properties.reserved.
   • see microbundle's normalization of the object before passing it to Terser.
3. Terser may add a numeric props.cname key to nameCache. Nobody know what it does.