Terser error: unknown field extractComments

[techbridgedev]

Builds are failing with multiple errors (example below):

assets/js/9206.e37e4cb3.js from Terser plugin
unknown field `extractComments`, expected one of `parse`, `compress`, `mangle`, `format`, `output`, `ecma`, `keepClassnames`, `keep_classnames`, `keepFnames`, `keep_fnames`, `module`, `safari10`, `toplevel`, `sourceMap`, `sourceMapIgnoreList`, `outputPath`, `inlineSourcesContent`, `emitSourceMapColumns` at line 1 column 151

Docusaurus v3.10.1.

At first I thought is was because I updated dependencies, but rolling back doesn't fix it. One previous deployment with the previous dependency tree worked.

The only other change from the previous deployment was I replaced a downloadable asset (a ZIP file). No pages or posts updated, no changes to my configuration.

I've tried deleting and reinstalling node_modules; deleting the build directory and rebuilding, running npm ci; none of these work.

FWIW, npm run start works for local production.

[slorber]

Sorry but it's impossible to do anything without a minimal repro.

[amasen02]

This error is coming from Rust/serde deserialization inside SWC (swc_ecma_minifier), which Docusaurus uses for production JS minification.

SWC's minifier options parser is strict: it only recognizes the exact fields listed in your error (parse, compress, mangle, format, etc.). When Webpack passes extractComments inside the options object handed to SWC, SWC fails because extractComments is a Webpack TerserPlugin option, not a valid SWC minifier option.

Since this began right after replacing a downloadable ZIP file, two scenarios typically cause this:

---

Cause 1: The ZIP File is Being Imported/Bundled as a Webpack Module

If the new ZIP asset was placed inside docs/ or src/ and referenced via Markdown file imports (e.g. [Download](./my-file.zip) or import zip from './file.zip'), Webpack's asset loader can generate an asset module chunk (like assets/js/9206.e37e4cb3.js) that runs through the minimizer pipeline with comments extraction enabled.

The Fix:

Move the ZIP file to Docusaurus's dedicated static/ directory so Webpack skips bundling and minification entirely:

1. Move the file:

   website/static/files/my-file.zip
   

2. In your Markdown docs, link to it using the pathname:// protocol to bypass Webpack bundling:

   [Download Archive](pathname:///files/my-file.zip)

Files in static/ are copied verbatim to the build output and are completely isolated from the Terser/SWC minification step.

---

Cause 2: Custom Webpack / Plugin Configuration

If any plugin or configureWebpack hook in docusaurus.config.js configures TerserPlugin, verify that extractComments is placed at the top level of the plugin options and not inside terserOptions:

// Incorrect (causes SWC unknown field error):
new TerserPlugin({
  terserOptions: {
    extractComments: false, // <-- Invalid inside terserOptions
  },
})

// Correct:
new TerserPlugin({
  extractComments: false, // <-- Root-level option only
  terserOptions: {
    compress: true,
  },
})

---

Cause 3: Temporary Fallback for SWC Minimizer

If you are using Docusaurus's Faster flags in docusaurus.config.js, you can temporarily revert the JavaScript minimizer to standard Terser to bypass the SWC schema validation:

// docusaurus.config.js
module.exports = {
  future: {
    experimental_faster: {
      swcJsMinimizer: false, // Uses standard Terser instead of SWC
    },
  },
};

Moving the ZIP to static/ with pathname:/// is the permanent fix.

[techbridgedev]

Thanks for the reply. The problem went away after a recent Docusaurus update. FWIW, causes 1 and 2 did not apply in my case.