oxc-project__oxc/napi/minify

Oxc Minify

See usage instructions.

This is alpha software and may yield incorrect results, feel free to submit a bug report.

Performance and Compression Size

See minification-benchmarks for details.

The current version already outperforms esbuild, but it still lacks a few key minification techniques such as constant inlining and dead code removal, which we plan to implement next.

Caveats

To maximize performance, oxc-minify assumes the input code is semantically correct. It uses oxc-parser's fast mode to parse the input code, which does not check for semantic errors related to symbols and scopes.

API

Functions

// Synchronous minification
minifySync(
  filename: string,
  sourceText: string,
  options?: MinifyOptions,
): MinifyResult

// Asynchronous minification
minify(
  filename: string,
  sourceText: string,
  options?: MinifyOptions,
): Promise<MinifyResult>

Use minifySync for synchronous minification. Use minify for asynchronous minification, which can be beneficial in I/O-bound or concurrent scenarios, though it adds async overhead.

Example

import { minifySync } from "oxc-minify";

const filename = "test.js";
const code = "const x = 'a' + 'b'; console.log(x);";
const options = {
  compress: {
    target: "esnext",
  },
  mangle: {
    toplevel: false,
  },
  codegen: {
    removeWhitespace: true,
  },
  sourcemap: true,
};
const result = minifySync(filename, code, options);
// Or use async version: const result = await minify(filename, code, options);

console.log(result.code);
console.log(result.map);

Property-name mangling

Property mangling is opt-in and independent from identifier mangling. include is a JavaScript RegExp and is required when mangleProps is present. Its source and flags are compiled with Rust's regex engine. Flags i, m, s, and u are supported. Other JavaScript flags and unsupported syntax are reported in errors.

const result = minifySync("component.js", source, {
  mangle: false,
  mangleProps: {
    include: /^_/,
    exclude: /^__public/,
    reserved: ["_externalApi"],
    quoted: false,
    cache: previousResult?.mangleCache,
  },
});

saveCache(result.mangleCache);

The returned mangleCache contains the input cache plus newly assigned names when parsing finishes without errors, sorted by original name. A false cache value keeps that property unchanged. Feeding the cache back keeps recorded mappings stable for later unminified input, but the cache does not discover unchanged names that exist only in another input. Callers coordinating separate files must pin or reserve those names explicitly. Property mappings are single-application: do not minify already-mangled output with the same cache. Custom target names may be shared deliberately, but must be valid JavaScript IdentifierName values and cannot be __proto__, constructor, or prototype. The original name __proto__ is always reserved and cannot be used as a cache key.

With quoted: false, quoting is handled per occurrence: obj._field is eligible while obj["_field"] is not. Property mangling assumes matching properties are never accessed through arbitrary dynamic strings. Use /* @__KEY__ */ "_field" for a string that semantically names a property, such as a reflective API argument. Names reached through direct eval, the Function constructor, or with must be reserved or excluded explicitly.

Properties owned by unminified code, imported module namespaces, globals, DOM objects, or other host APIs must also be excluded or reserved.

Assumptions

oxc-minify makes some assumptions about the source code.

See https://github.com/oxc-project/oxc/blob/main/crates/oxc_minifier/README.md#assumptions for details.

Supports WASM

See https://stackblitz.com/edit/oxc-minify for usage example.