fix(lazyBundleIdPlugin): fixed the issue with creation of orphaned '.map' files in the distribution directory

[Jagget]

Fix: Orphaned Sourcemap Files in Browser Builds

The bug is introduced between v4.27.1 and v4.38.3

(I only have these two versions locally and it is not there in v4.27.1, but it is there in v4.38.3)

Problem

When sourceMap: true is enabled in stencil.config.ts, the build process generates orphaned .map files in the browser build output directory (e.g., /dist/my-library/). These are sourcemap files that exist without their corresponding JavaScript files.

Example of Orphaned Files

/dist/my-library/my-component.entry.esm.js.map           (no .js file)
/dist/my-library/my-another-component.entry.esm.js.map   (no .js file)
/dist/my-library/loader.esm.js.map                       (no .js file)
/dist/my-library/p-CsMNLVxY.system.js.map                (no .js file)

While the actual JavaScript files exist with different names:

/dist/my-library/p-667b042f.entry.esm.js                 (has .map file)
/dist/my-library/p-a1b2c3d4.entry.esm.js                 (has .map file)

Root Cause

The issue was caused by bugs in the lazyBundleIdPlugin and file writing logic:

1. Orphaned Sourcemaps After File Renaming

When lazyBundleIdPlugin renames files from my-component.esm.js to p-667b042f.entry.js (when hashing is enabled), Rollup has already created the sourcemap file my-component.esm.js.map in the bundle. The plugin wasn't deleting the old sourcemap, leaving it orphaned.

2. Loader Files Not Written for Browser Builds

The writeLazyEntry() function skips writing loader files for browser builds (returns early at line 268-270), but their sourcemaps remained in the Rollup bundle, creating orphaned files like loader.esm.js.map and p-xxx.system.js.map.

3. Race Conditions in File Writes

The writeLazyModule(), writeLazyEntry(), and writeLazyChunk() functions were not properly awaiting both JS and sourcemap file writes atomically, which could lead to incomplete writes in edge cases.

Solution

Changes Made

1. src/compiler/output-targets/dist-lazy/lazy-bundleid-plugin.ts

Purpose: Clean up orphaned sourcemaps during file renaming

Changes:

• Delete orphaned sourcemaps when renaming files: When the plugin renames a file (e.g., my-component.esm.js → p-667b042f.entry.js), it now deletes the old sourcemap file (my-component.esm.js.map) from the Rollup bundle to prevent orphaned files
• Delete loader sourcemaps for browser builds: Since writeLazyEntry() skips writing loader files for browser builds, their sourcemaps must be removed from the bundle to prevent orphaned files
• Minor refactoring: Extract newFileName to a variable for clarity and to enable the orphaned sourcemap check

2. src/compiler/output-targets/dist-lazy/write-lazy-entry-module.ts

Purpose: Fix race condition in file writes

Changes:

• Return Promise.all(): Ensures both JS and sourcemap files are written atomically before the function completes, preventing potential race conditions

3. src/compiler/output-targets/dist-lazy/generate-lazy-module.ts

Purpose: Fix race conditions in file writes

Changes:

• Fixed writeLazyChunk(): Properly return Promise.all() for atomic writes of JS and sourcemap files
• Fixed writeLazyEntry(): Properly return Promise.all() for atomic writes of JS and sourcemap files

Testing

To verify the fix:

1. Enable sourcemaps in your stencil.config.ts:

   export const config: Config = {
     sourceMap: true, // Default is true, but explicitly set for clarity
     // ... other config
   };

2. Build the project:

   npm run build

3. Check for orphaned sourcemap files:

   find ./dist -name "*.map" -type f | while read map; do
     js="${map%.map}"
     [ ! -f "$js" ] && echo "Orphaned: $map"
   done

4. Expected result: No orphaned files should be reported

Impact

• Fixes: Orphaned sourcemap files in browser builds
• Improves: Build output cleanliness and correctness
• No breaking changes: All changes are internal to the build process
• Performance: No performance impact (minimal additional logic in build plugin)