feat: rename terserOptions to minimizerOptions

Introduce `minimizerOptions` as the canonical name for the options that
are forwarded to the active minimizer (Terser by default, or whatever
function is supplied via `minify`). The previous `terserOptions` key
keeps working as a deprecated alias; passing both at the same time now
throws an explicit error.

Schema, JSDoc-derived TypeScript declarations, README examples and tests
have been updated to favour the new name while still validating the old
one.

Author: claude

README.md

@@ -74,7 +74,7 @@ Using supported `devtool` values enable source map generation.
 - **[`exclude`](#exclude)**
 - **[`parallel`](#parallel)**
 - **[`minify`](#minify)**
-- **[`terserOptions`](#terseroptions)**
+- **[`minimizerOptions`](#minimizeroptions)**
 - **[`extractComments`](#extractcomments)**
 
 ### `test`
@@ -287,7 +287,7 @@ Allows you to override the default minify function.
 By default plugin uses [terser](https://github.com/terser/terser) package.
 Useful for using and testing unpublished versions or forks.
 
-An array of functions can also be provided to chain multiple minimizers — the output of each minimizer is fed as input to the next. When an array is used, the [`terserOptions`](#terseroptions) option may also be an array (index-paired with `minify`) or a single object that is reused for every minimizer.
+An array of functions can also be provided to chain multiple minimizers — the output of each minimizer is fed as input to the next. When an array is used, the [`minimizerOptions`](#minimizeroptions) option may also be an array (index-paired with `minify`) or a single object that is reused for every minimizer.
 
 > **Warning**
 >
@@ -300,7 +300,7 @@ An array of functions can also be provided to chain multiple minimizers — the
 ```js
 // Can be async
 const minify = (input, sourceMap, minimizerOptions, extractsComments) => {
-  // The `minimizerOptions` option contains option from the `terserOptions` option
+  // The `minimizerOptions` argument contains options from the `minimizerOptions` plugin option
   // You can use `minimizerOptions.myCustomOption`
 
   // Custom logic for extract comments
@@ -333,7 +333,7 @@ module.exports = {
     minimize: true,
     minimizer: [
       new TerserPlugin({
-        terserOptions: {
+        minimizerOptions: {
           myCustomOption: true,
         },
         minify,
@@ -346,7 +346,7 @@ module.exports = {
 #### `array`
 
 If an array of functions is passed to the `minify` option, the output of each
-minimizer is fed as input to the next one. The `terserOptions` option can be
+minimizer is fed as input to the next one. The `minimizerOptions` option can be
 either an array of option objects (index-paired with `minify`) or a single
 object that will be shared by all minimizers. Warnings, errors and extracted
 comments from all minimizers are merged together.
@@ -360,8 +360,8 @@ module.exports = {
     minimizer: [
       new TerserPlugin({
         minify: [TerserPlugin.terserMinify, TerserPlugin.swcMinify],
-        // `terserOptions` can be an array of options, one per `minify` entry
-        terserOptions: [
+        // `minimizerOptions` can be an array of options, one per `minify` entry
+        minimizerOptions: [
           // Options for `TerserPlugin.terserMinify`
           { mangle: false },
           // Options for `TerserPlugin.swcMinify`
@@ -373,12 +373,12 @@ module.exports = {
 };
 ```
 
-### `terserOptions`
+### `minimizerOptions`
 
 Type:
 
 ```ts
-interface terserOptions {
+interface minimizerOptions {
   compress?: boolean | CompressOptions;
   ecma?: ECMA;
   enclose?: boolean | string;
@@ -397,18 +397,25 @@ interface terserOptions {
   toplevel?: boolean;
 }
 
-type options = terserOptions | terserOptions[];
+type options = minimizerOptions | minimizerOptions[];
 ```
 
 Default: [default](https://github.com/terser/terser#minify-options)
 
-Terser [options](https://github.com/terser/terser#minify-options).
+Options for the active minimizer. With the default Terser minify, see Terser's
+[minify options](https://github.com/terser/terser#minify-options).
 
-When the [`minify`](#minify) option is an array of minimizers, `terserOptions`
+When the [`minify`](#minify) option is an array of minimizers, `minimizerOptions`
 can also be an array. Each element is passed to the minimizer at the same
 index in the `minify` array. If a single object is provided instead, it is
 reused for every minimizer.
 
+> **Note**
+>
+> `terserOptions` is kept as a deprecated alias of `minimizerOptions` for
+> backwards compatibility — passing either is equivalent. Passing both at the
+> same time throws an error. Prefer `minimizerOptions` in new code.
+
 **webpack.config.js**
 
 ```js
@@ -417,7 +424,7 @@ module.exports = {
     minimize: true,
     minimizer: [
       new TerserPlugin({
-        terserOptions: {
+        minimizerOptions: {
           ecma: undefined,
           parse: {},
           compress: {},
@@ -492,7 +499,7 @@ By default, extract only comments using `/^\**!|@preserve|@license|@cc_on/i` Reg
 
 If the original file is named `foo.js`, then the comments will be stored to `foo.js.LICENSE.txt`.
 
-The `terserOptions.format.comments` option specifies whether the comment will be preserved - i.e., it is possible to preserve some comments (e.g. annotations) while extracting others, or even preserve comments that have already been extracted.
+The `minimizerOptions.format.comments` option specifies whether the comment will be preserved - i.e., it is possible to preserve some comments (e.g. annotations) while extracting others, or even preserve comments that have already been extracted.
 
 #### `boolean`
 
@@ -741,7 +748,7 @@ module.exports = {
     minimize: true,
     minimizer: [
       new TerserPlugin({
-        terserOptions: {
+        minimizerOptions: {
           format: {
             comments: /@license/i,
           },
@@ -765,7 +772,7 @@ module.exports = {
     minimize: true,
     minimizer: [
       new TerserPlugin({
-        terserOptions: {
+        minimizerOptions: {
           format: {
             comments: false,
           },
@@ -790,9 +797,9 @@ module.exports = {
     minimizer: [
       new TerserPlugin({
         minify: TerserPlugin.uglifyJsMinify,
-        // `terserOptions` options will be passed to `uglify-js`
+        // `minimizerOptions` will be passed to `uglify-js`
         // Link to options - https://github.com/mishoo/UglifyJS#minify-options
-        terserOptions: {},
+        minimizerOptions: {},
       }),
     ],
   },
@@ -818,9 +825,9 @@ module.exports = {
     minimizer: [
       new TerserPlugin({
         minify: TerserPlugin.swcMinify,
-        // `terserOptions` options will be passed to `swc` (`@swc/core`)
+        // `minimizerOptions` will be passed to `swc` (`@swc/core`)
         // Link to options - https://swc.rs/docs/config-js-minify
-        terserOptions: {},
+        minimizerOptions: {},
       }),
     ],
   },
@@ -844,16 +851,16 @@ module.exports = {
     minimizer: [
       new TerserPlugin({
         minify: TerserPlugin.esbuildMinify,
-        // `terserOptions` options will be passed to `esbuild`
+        // `minimizerOptions` will be passed to `esbuild`
         // Link to options - https://esbuild.github.io/api/#minify
         // Note: the `minify` options is true by default (and override other `minify*` options), so if you want to disable the `minifyIdentifiers` option (or other `minify*` options) please use:
-        // terserOptions: {
+        // minimizerOptions: {
         //   minify: false,
         //   minifyWhitespace: true,
         //   minifyIdentifiers: false,
         //   minifySyntax: true,
         // },
-        terserOptions: {},
+        minimizerOptions: {},
       }),
     ],
   },
@@ -878,7 +885,7 @@ module.exports = {
         test: /\.json$/,
         minify: TerserPlugin.jsonMinify,
         // We are supporting `space` and `replacer` options, you can set them below
-        terserOptions: {},
+        minimizerOptions: {},
       }),
     ],
   },
@@ -927,7 +934,7 @@ module.exports = {
     minimize: true,
     minimizer: [
       new TerserPlugin({
-        terserOptions: {
+        minimizerOptions: {
           compress: true,
         },
       }),
@@ -950,27 +957,27 @@ module.exports = {
     minimizer: [
       new TerserPlugin<SwcOptions>({
         minify: TerserPlugin.swcMinify,
-        terserOptions: {
+        minimizerOptions: {
           // `swc` options
         },
       }),
       new TerserPlugin<UglifyJSOptions>({
         minify: TerserPlugin.uglifyJsMinify,
-        terserOptions: {
+        minimizerOptions: {
           // `uglif-js` options
         },
       }),
       new TerserPlugin<EsbuildOptions>({
         minify: TerserPlugin.esbuildMinify,
-        terserOptions: {
+        minimizerOptions: {
           // `esbuild` options
         },
       }),
 
       // Alternative usage:
       new TerserPlugin<TerserOptions>({
         minify: TerserPlugin.terserMinify,
-        terserOptions: {
+        minimizerOptions: {
           // `terser` options
         },
       }),

src/index.js

@@ -153,7 +153,7 @@ const {
 
 /**
  * @template T
- * @typedef {T extends import("terser").MinifyOptions ? { minify?: MinimizerImplementation<T> | undefined, terserOptions?: MinimizerOptions<T> | undefined } : { minify: MinimizerImplementation<T>, terserOptions?: MinimizerOptions<T> | undefined }} DefinedDefaultMinimizerAndOptions
+ * @typedef {T extends import("terser").MinifyOptions ? { minify?: MinimizerImplementation<T> | undefined, minimizerOptions?: MinimizerOptions<T> | undefined, terserOptions?: MinimizerOptions<T> | undefined } : { minify: MinimizerImplementation<T>, minimizerOptions?: MinimizerOptions<T> | undefined, terserOptions?: MinimizerOptions<T> | undefined }} DefinedDefaultMinimizerAndOptions
  */
 
 /**
@@ -183,14 +183,28 @@ class TerserPlugin {
       minify = /** @type {MinimizerImplementation<T>} */ (
         /** @type {unknown} */ (terserMinify)
       ),
-      terserOptions = /** @type {MinimizerOptions<T>} */ ({}),
+      minimizerOptions,
+      terserOptions,
       test = /\.[cm]?js(\?.*)?$/i,
       extractComments = true,
       parallel = true,
       include,
       exclude,
     } = options || {};
 
+    if (
+      typeof minimizerOptions !== "undefined" &&
+      typeof terserOptions !== "undefined"
+    ) {
+      throw new Error(
+        "The `minimizerOptions` and `terserOptions` options can't be used together. Please use only `minimizerOptions` (`terserOptions` is a deprecated alias).",
+      );
+    }
+
+    const resolvedMinimizerOptions =
+      /** @type {MinimizerOptions<T>} */
+      (minimizerOptions || terserOptions || {});
+
     /**
      * @private
      * @type {InternalPluginOptions<T>}
@@ -203,7 +217,7 @@ class TerserPlugin {
       exclude,
       minimizer: {
         implementation: minify,
-        options: terserOptions,
+        options: resolvedMinimizerOptions,
       },
     };
   }

src/options.json

@@ -64,8 +64,26 @@
         }
       ]
     },
-    "terserOptions": {
+    "minimizerOptions": {
       "description": "Options for `terser` (by default) or custom `minify` function.",
+      "link": "https://github.com/webpack/terser-webpack-plugin#minimizeroptions",
+      "anyOf": [
+        {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "additionalProperties": true,
+            "type": "object"
+          }
+        }
+      ]
+    },
+    "terserOptions": {
+      "description": "Deprecated alias for `minimizerOptions`. Options for `terser` (by default) or custom `minify` function.",
       "link": "https://github.com/webpack/terser-webpack-plugin#terseroptions",
       "anyOf": [
         {

test/__snapshots__/minimizerOptions-option.test.js.snap

@@ -0,0 +1,54 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`minimizerOptions option should accept \`minimizerOptions\` and apply them like \`terserOptions\`: assets 1`] = `
+Object {
+  "main.js": "!function() {
+    var __webpack_modules__ = {
+        326: function(module) {
+            var abc, Person = {
+                firstName: null,
+                lastName: null
+            }, Employee = Object.create(Person, {
+                id: {
+                    value: null,
+                    enumerable: !0,
+                    configurable: !0,
+                    writable: !0
+                }
+            }), Manager = Object.create(Employee, {
+                department: {
+                    value: null,
+                    enumerable: !0,
+                    configurable: !0,
+                    writable: !0
+                }
+            });
+            module.exports = {
+                Person: Person,
+                Employee: Employee,
+                Manager: Manager
+            }, abc = {
+                data() {
+                    return {
+                        a: 2
+                    };
+                }
+            }, console.log(abc);
+        }
+    }, __webpack_module_cache__ = {};
+    (function __webpack_require__(moduleId) {
+        var cachedModule = __webpack_module_cache__[moduleId];
+        if (void 0 !== cachedModule) return cachedModule.exports;
+        var module = __webpack_module_cache__[moduleId] = {
+            exports: {}
+        };
+        return __webpack_modules__[moduleId](module, module.exports, __webpack_require__), 
+        module.exports;
+    })(326);
+}();",
+}
+`;
+
+exports[`minimizerOptions option should accept \`minimizerOptions\` and apply them like \`terserOptions\`: errors 1`] = `Array []`;
+
+exports[`minimizerOptions option should accept \`minimizerOptions\` and apply them like \`terserOptions\`: warnings 1`] = `Array []`;

test/__snapshots__/validate-options.test.js.snap

@@ -144,7 +144,7 @@ exports[`validation validate 12`] = `
 "Invalid options object. Terser Plugin has been initialized using an options object that does not match the API schema.
  - options.terserOptions should be one of these:
    object { … } | [object { … }, ...] (should not have fewer than 1 item)
-   -> Options for \`terser\` (by default) or custom \`minify\` function.
+   -> Deprecated alias for \`minimizerOptions\`. Options for \`terser\` (by default) or custom \`minify\` function.
    -> Read more at https://github.com/webpack/terser-webpack-plugin#terseroptions
    Details:
     * options.terserOptions should be an object:
@@ -213,5 +213,25 @@ exports[`validation validate 16`] = `
 exports[`validation validate 17`] = `
 "Invalid options object. Terser Plugin has been initialized using an options object that does not match the API schema.
  - options has an unknown property 'unknown'. These properties are valid:
-   object { test?, include?, exclude?, terserOptions?, extractComments?, parallel?, minify? }"
+   object { test?, include?, exclude?, minimizerOptions?, terserOptions?, extractComments?, parallel?, minify? }"
+`;
+
+exports[`validation validate 18`] = `
+"Invalid options object. Terser Plugin has been initialized using an options object that does not match the API schema.
+ - options.minimizerOptions should be a non-empty array."
 `;
+
+exports[`validation validate 19`] = `
+"Invalid options object. Terser Plugin has been initialized using an options object that does not match the API schema.
+ - options.minimizerOptions should be one of these:
+   object { … } | [object { … }, ...] (should not have fewer than 1 item)
+   -> Options for \`terser\` (by default) or custom \`minify\` function.
+   -> Read more at https://github.com/webpack/terser-webpack-plugin#minimizeroptions
+   Details:
+    * options.minimizerOptions should be an object:
+      object { … }
+    * options.minimizerOptions should be an array:
+      [object { … }, ...] (should not have fewer than 1 item)"
+`;
+
+exports[`validation validate 20`] = `"The \`minimizerOptions\` and \`terserOptions\` options can't be used together. Please use only \`minimizerOptions\` (\`terserOptions\` is a deprecated alias)."`;