feat: expand minifier docs and transformer global variable replacement docs

Author: sapphi-red

.vitepress/config/en.ts

@@ -107,14 +107,39 @@ export const enConfig = defineLocaleConfig("root", {
                   text: "Plugins",
                   link: "/docs/guide/usage/transformer/plugins",
                 },
+                {
+                  text: "Global Variable Replacement",
+                  link: "/docs/guide/usage/transformer/global-variable-replacement",
+                },
                 {
                   text: "Isolated Declarations",
                   link: "/docs/guide/usage/transformer/isolated-declarations",
                 },
               ],
             },
             { text: "Formatter", link: "/docs/guide/usage/formatter" },
-            { text: "Minifier", link: "/docs/guide/usage/minifier" },
+            {
+              text: "Minifier",
+              link: "/docs/guide/usage/minifier",
+              items: [
+                {
+                  text: "Dead Code Elimination",
+                  link: "/docs/guide/usage/minifier/dead-code-elimination",
+                },
+                {
+                  text: "Syntax Normalization",
+                  link: "/docs/guide/usage/minifier/syntax-normalization",
+                },
+                {
+                  text: "Mangling",
+                  link: "/docs/guide/usage/minifier/mangling",
+                },
+                {
+                  text: "Whitespace Stripping",
+                  link: "/docs/guide/usage/minifier/whitespace-stripping",
+                },
+              ],
+            },
             { text: "Resolver", link: "/docs/guide/usage/resolver" },
           ],
         },

src/docs/guide/usage/minifier.md

@@ -5,6 +5,17 @@
 We recommend thoroughly testing its output before deploying to production environments.
 :::
 
+## Features
+
+- [Eliminate dead code.](./minifier/dead-code-elimination)
+- [Transforms syntaxes to make the output shorter and repetitive.](./minifier/syntax-normalization)
+- [Mangle variable names.](./minifier/mangling)
+- [Remove whitespace and comments.](./minifier/whitespace-stripping)
+
+## Assumptions
+
+To allow better optimizations, Oxc minifier makes some assumptions about your code. See [Assumptions document](https://github.com/oxc-project/oxc/blob/main/crates/oxc_minifier/docs/ASSUMPTIONS.md) for more information.
+
 ## Installation
 
 ### With Rolldown
@@ -22,6 +33,10 @@ Use the umbrella crate [oxc][url-oxc-crate] with the `minifier` feature.
 
 Rust usage example can be found [here](https://github.com/oxc-project/oxc/blob/main/crates/oxc_minifier/examples/minifier.rs).
 
+## Integrations
+
+- [`unplugin-oxc`](https://github.com/unplugin/unplugin-oxc)
+
 <!-- Links -->
 
 [url-oxc-crate]: https://docs.rs/oxc

src/docs/guide/usage/minifier/dead-code-elimination.md

@@ -0,0 +1,144 @@
+# Dead Code Elimination
+
+Oxc minifier supports eliminating dead code. For example, it removes the statements inside a `if (false)` block and the unused private class fields.
+
+This feature is always enabled, but you can remove more code by enabling some options.
+
+::: tip Useful features in the transformer
+
+Other than the options below, you can also use [the `define` feature in the transformer](/docs/guide/usage/transformer/global-variable-replacement#define) to replace global identifiers with constant expressions to remove more dead code.
+
+:::
+
+## Drop Console
+
+You can remove all `console.*` calls by enabling the `dropConsole` option. This option behaves similar to [Terser](https://terser.org/)'s `drop_console` option and [esbuild's `drop: ['console']` option](https://esbuild.github.io/api/#drop).
+
+```js
+// input
+const bar = window.bar();
+console.log("foo", bar, baz());
+
+// output
+const bar = window.bar();
+```
+
+```js
+// Example
+import { minify } from "oxc-minify";
+
+const result = minify("lib.js", code, {
+  compress: {
+    dropConsole: true,
+  },
+});
+```
+
+::: warning The whole call expression is removed
+
+Note that this option removes the whole call expression including the arguments. This is intentional because removing the evaluation of call arguments is useful for improving the runtime performance if those are expensive to compute. However, if any of those arguments have side effects, this transformation will change the behavior of your code.
+
+<!-- TODO: suggest pure functions option when exposed -->
+
+:::
+
+## Drop Debugger
+
+You can remove all `debugger` statements by enabling the `dropDebugger` option. This option is enabled by default. This option behaves similar to [Terser](https://terser.org/)'s `drop_debugger` option and [esbuild's `drop: ['debugger']` option](https://esbuild.github.io/api/#drop).
+
+```js
+// input
+debugger;
+
+// output
+```
+
+```js
+// Example
+import { minify } from "oxc-minify";
+
+const result = minify("lib.js", code, {
+  compress: {
+    dropDebugger: true,
+  },
+});
+```
+
+## Drop Labels
+
+You can remove all labeled statements with specified labels by enabling the `dropLabels` option. This option behaves similar to [esbuild's `dropLabels` option](https://esbuild.github.io/api/#drop-labels).
+
+```js
+// input
+DEV: console.log("foo");
+console.log("bar");
+
+// output
+console.log("bar");
+```
+
+```js
+// Example
+import { minify } from "oxc-minify";
+
+const result = minify("lib.js", code, {
+  compress: {
+    dropLabels: ["DEV"],
+  },
+});
+```
+
+## Unused Declarations
+
+All unused function / class / variable declarations are removed by default. You can keep them by using the `unused` option.
+
+```js
+// input
+{
+  function foo() {}
+}
+
+// output
+```
+
+```js
+// Example
+import { minify } from "oxc-minify";
+
+const result = minify("lib.js", code, {
+  compress: {
+    unused: true, // or "keep_assign"
+  },
+});
+```
+
+## Keep `name` Property Values
+
+By default, Oxc minifier assumes that your code does not rely on the `name` property of functions / classes. This is because the `name` property is inferred from the function / class name or the variable name and keeping the original name would prevent reducing the output size.
+
+To keep the `name` property values, you can use the `keepNames` option.
+
+```js
+// input
+var bar = function foo() {};
+
+// output
+var bar = function foo() {};
+```
+
+```js
+// Example
+import { minify } from "oxc-minify";
+
+const result = minify("lib.js", code, {
+  compress: {
+    keepNames: true, // shorthand of { function: true, class: true }
+  },
+});
+```
+
+::: tip `mangle.keepNames` option
+
+If you are using the mangling feature, you may also want to enable [the `mangle.keepNames` option](./mangling#keep-name-property-values).
+
+:::

src/docs/guide/usage/minifier/mangling.md

@@ -0,0 +1,87 @@
+# Mangling
+
+Oxc minifier supports mangling variable names and private class fields.
+
+This feature is enabled by default and can be disabled by setting the `mangle` option to `false`.
+
+## Top Level Variables
+
+Top level variables are not mangled by default for non module code. You can enable mangling for top level variables by setting the `mangle.toplevel` option to `true`.
+
+```js
+// input
+var foo = 1;
+
+// output
+var e = 1;
+```
+
+```js
+// Example
+import { minify } from "oxc-minify";
+
+const result = minify("lib.js", code, {
+  module: false, // non-module code
+  compress: {
+    mangle: {
+      toplevel: true,
+    },
+  },
+});
+```
+
+## Keep `name` Property Values
+
+Mangling variable names can change the `name` property values of functions / classes. You can keep the original `name` property values by enabling the `mangle.keepNames` option.
+
+```js
+// input
+var foo = function() {};
+
+// output
+var foo = function() {};
+```
+
+```js
+// Example
+import { minify } from "oxc-minify";
+
+const result = minify("lib.js", code, {
+  compress: {
+    mangle: {
+      keepNames: true, // shorthand of { function: true, class: true }
+    },
+  },
+});
+```
+
+::: tip `compress.keepNames` option
+
+When enabling this option, you may also want to enable [the `compress.keepNames` option](./dead-code-elimination#keep-name-property-values).
+
+:::
+
+## Debugging The Mangler
+
+To debug the mangler, you can enable the `mangle.debug` option. When this option is enabled, the mangler will use `slot_0`, `slot_1`, ... as variable names.
+
+```js
+// input
+var foo = 1;
+
+// output
+var slot_0 = 1;
+```
+
+```js
+// Example
+import { minify } from "oxc-minify";
+
+const result = minify("lib.js", code, {
+  compress: {
+    mangle: {
+      debug: true,
+    },
+  },
+});
+```

src/docs/guide/usage/minifier/syntax-normalization.md

@@ -0,0 +1,69 @@
+# Syntax Normalization
+
+Oxc minifier supports transforming syntaxes to make the output shorter and repetitive.
+
+This feature is enabled by default and can be disabled by setting the `compress` option to `false`.
+
+## Target
+
+Oxc minifier uses some syntaxes that are only supported in newer environments. You can specify the target environment by setting the `target` option. The default value is `esnext`, which allows the use of any syntaxes that are supported by the latest ECMAScript standard. The supported value is same as [the `target` option in the transformer](/docs/guide/usage/transformer/lowering#target).
+
+```js
+import { minify } from "oxc-minify";
+
+const result = minify("lib.js", code, {
+  compress: {
+    target: "chrome87",
+  },
+});
+```
+
+## Join Variables
+
+By default, consecutive variable declarations are merged into a single declaration. You can disable this behavior by setting the `compress.joinVars` option to `false`.
+
+```js
+// input
+var foo = 1;
+var bar = 2;
+
+// output
+var foo = 1;
+var bar = 2;
+```
+
+```js
+// Example
+import { minify } from "oxc-minify";
+
+const result = minify("lib.js", code, {
+  compress: {
+    joinVars: false,
+  },
+});
+```
+
+## Sequences
+
+By default, consecutive statements are merged into a single statement using the comma operator. You can disable this behavior by setting the `compress.sequences` option to `false`.
+
+```js
+// input
+foo();
+bar();
+
+// output
+foo();
+bar();
+```
+
+```js
+// Example
+import { minify } from "oxc-minify";
+
+const result = minify("lib.js", code, {
+  compress: {
+    sequences: false,
+  },
+});
+```

src/docs/guide/usage/minifier/whitespace-stripping.md

@@ -0,0 +1,5 @@
+# Whitespace Stripping
+
+Oxc minifier supports removing whitespace and comments.
+
+This feature is enabled by default and can be disabled by setting the `codegen.removeWhitespace` option to `false`.

src/docs/guide/usage/transformer.md

@@ -6,6 +6,7 @@
 - [Transforming TypeScript to JavaScript.](./transformer/typescript)
 - [Transforming JSX to JavaScript, with built-in React Refresh.](./transformer/jsx)
 - [Built-in support for popular plugins like styled-components.](./transformer/plugins)
+- [Replacing global variables.](./transformer/global-variable-replacement)
 - [TypeScript Isolated Declarations Emit without using the TypeScript compiler.](./transformer/isolated-declarations)
 
 ## Installation