Magento 2.4.9 JS Merge Bug: How Source Map Comments Break Your Admin Pages

Unmasking the Silent Killer: How Magento 2.4.9's JS Merge Can Break Your Admin

As e-commerce migration experts at Shopping Mover, we often encounter subtle yet critical issues that can derail an otherwise smooth Magento upgrade. One such issue, highlighted in GitHub issue #40905, reveals a significant flaw in Magento 2.4.9's JavaScript merging strategy that can lead to broken admin pages and a frustrating user experience. This insight delves into the problem, its root cause, and the proposed solution, offering crucial information for developers and merchants alike.

The Core Problem: Uncaught SyntaxError in Merged JS

Imagine upgrading your Magento store to version 2.4.9, enabling standard performance optimizations like JavaScript merging, and then finding your admin pages, such as Catalog → Categories, completely broken. This is precisely the scenario described in the GitHub issue. Users would encounter an Uncaught SyntaxError: expected expression, got '}' in the browser console, rendering critical admin functionality unusable.

The culprit? A seemingly innocuous single-line comment: //# sourceMappingURL=.... Many third-party modules, like the Trustpilot Reviews module mentioned in the issue, ship pre-minified JavaScript files (e.g., admin.min.js) that end with these source map comments. When Magento's JS merge combines such a file with the next one in the bundle, a critical error occurs.

The Mechanism of Failure: Comments Swallowing Code

The issue arises because Magento 2.4.9, with JavaScript merging enabled, concatenates minified files using only a semicolon (;) as a delimiter, without adding a newline character. A single-line comment in JavaScript (//) extends to the end of the line. Therefore, if a file ends with //# sourceMappingURL=admin.min.js.map and the next file is appended immediately after it on the same physical line, the entire subsequent file gets commented out.

For example, a merged line might look like this:

//# sourceMappingURL=admin.min.js.map;require(['Magento_Variable/variables','mage/adminhtml/browser']);;require(['jquery','Magento_Ui/js/modal/confirm',...],function(jQuery,confirm){'use strict';function categoryDelete(url){...

Everything after //# becomes a comment. This means crucial JavaScript code, like the require([...]) bootstraps and category functions, never executes. This leads to unbalanced braces later in the bundle, triggering the Uncaught SyntaxError and preventing the page from loading correctly.

Deep Dive: The Root Cause in Magento's Core

The core of this problem lies within the Magento\Framework\View\Asset\MergeStrategy\Direct class. Specifically, the constant MERGE_DELIMITER_JS is defined as a bare semicolon (';') without a newline. The composeMergedContent method uses this delimiter to join the content of multiple JavaScript assets.

private const MERGE_DELIMITER_JS = ';';
...
protected function _getFilesContentDelimiter($contentType)
{
    if ($c 'js') {
        return self::MERGE_DELIMITER_JS; // ';' — no newline
    }
    return self::MERGE_DELIMITER_EMPTY;
}

Because pre-minified *.min.js files are merged verbatim (Magento's minifier, tedivm/jshrink, doesn't re-minify them or remove these specific comments), the trailing //# sourceMappingURL comment persists into the merged bundle, directly causing the issue.

The Proposed Solution: A Simple Newline

The elegant and backward-compatible fix proposed in the issue is to simply add a newline character to the JavaScript merge delimiter. By changing MERGE_DELIMITER_JS to "; ", each merged file is guaranteed to start on a new line, preventing any trailing single-line comments from swallowing subsequent code.

private const MERGE_DELIMITER_JS = ";
";

This ensures that the ECMAScript specification for single-line comments is respected, and all merged files execute as intended. While the issue was categorized as S3 (affecting non-critical functionality without forcing a workaround), the practical impact of a broken admin page can be far more severe for a live store.

Shopping Mover's Take

This issue underscores the importance of thorough testing, especially for JavaScript functionality, during any Magento upgrade or migration. Even minor version bumps can introduce subtle regressions that impact performance optimizations or third-party extensions. For merchants considering a Magento migration or upgrade, understanding such technical nuances is crucial. At Shopping Mover, we emphasize comprehensive pre- and post-migration audits to identify and address such critical bugs, ensuring your new Magento store operates flawlessly from day one.