webpack-assets-manifest is not concurrency safe as the lockfile dependency used to guard against race conditions is unmaintained

[Judahmeek]

Last version for lockfile, which webpack-assets-manifest uses, was released 8 years ago.

[justin808]

This is what Gemini Pro says:

No, it is not considered "safe" for critical production builds.

Your suspicion is well-founded. Relying on the merge feature in webpack-assets-manifest for parallel builds is risky specifically because of its dependency on the lockfile package, which has been unmaintained for over 8 years.

Here is the breakdown of why this is unsafe and the better alternatives you should use.

🚨 The Risk: Why lockfile is a Problem

The lockfile package was written for an older era of Node.js and file systems. In a modern parallel build environment (e.g., parallel-webpack, multiple independent CI workers, or threaded builds), you face two primary risks:

1. Stale Locks (Build Hangs): If a build process crashes or is terminated abruptly (common in CI/CD pipelines), the 8-year-old logic may fail to detect the stale lock file (.lock). Subsequent builds might wait indefinitely for a lock that will never be released, causing your deployment pipeline to time out.
2. Race Conditions (Corrupted Manifests): File locking is notoriously OS-dependent. Modern file systems (like those in newer Docker containers or cloud storage mounts) may behave differently than the lockfile package expects, potentially allowing two processes to write to the JSON file simultaneously. This results in invalid JSON syntax and a broken production app.

🛠️ The Solution: 3 Safer Alternatives

Instead of relying on the plugin to merge the file while it's being written to, use one of these strategies to avoid the race condition entirely.

Option 1: The "Seed" Approach (Best for Multi-Compiler)

If you are running parallel builds via Webpack's Multi-Compiler mode (returning an array of configs in one webpack.config.js), you can share a single Javascript object between them. This keeps the data in memory and writes it once at the end.

Note: webpack-manifest-plugin handles this slightly better natively, but you can do it with webpack-assets-manifest by passing a shared object.

// webpack.config.js
const WebpackAssetsManifest = require('webpack-assets-manifest');

// 1. Create a shared object in memory
const sharedManifestData = {};

const config1 = {
  // ... config for build 1
  plugins: [
    new WebpackAssetsManifest({
      assets: sharedManifestData, // Pass the shared object
      output: 'assets-manifest.json',
    })
  ]
};

const config2 = {
  // ... config for build 2
  plugins: [
    new WebpackAssetsManifest({
      assets: sharedManifestData, // Pass the same object
      output: 'assets-manifest.json',
    })
  ]
};

module.exports = [config1, config2];

Option 2: The "Post-Build Merge" (Safest for Separate Processes)

If your parallel builds run as totally separate processes (e.g., separate CI jobs or npm run build:legacy & npm run build:modern), do not try to write to the same file.

1. Output separate files: Configure each build to output a unique manifest (e.g., manifest-legacy.json and manifest-modern.json).
2. Merge later: Run a tiny script after both builds finish to merge them. This completely eliminates the need for file locking.

// scripts/merge-manifests.js
const fs = require('fs');

const legacy = require('../dist/manifest-legacy.json');
const modern = require('../dist/manifest-modern.json');

const combined = { ...legacy, ...modern };

fs.writeFileSync('./dist/manifest.json', JSON.stringify(combined, null, 2));

Option 3: Switch to webpack-manifest-plugin

The alternative package, webpack-manifest-plugin, is generally more robust for standard use cases and allows you to pass a seed option to accumulating data, similar to Option 1.

Recommendation

Avoid the merge: true option in webpack-assets-manifest for parallel builds.
Use Option 2 (Post-Build Merge) if your builds are separate processes, as it is the only method that guarantees zero race conditions without relying on questionable file-locking logic.

Next Step:
Do you want a code snippet for a robust "merge script" that you can add to your package.json scripts to automate Option 2?

[justin808]

Option 2 is not so simple.

If you are running parallel builds (separate processes), avoiding conflicts in both the Cache and the Output directories is critical to prevent corruption and build errors.

Here is the breakdown of exactly what you need to isolate and how.

1. The Cache Directory (CRITICAL)

You must isolate the cache.
If two Webpack processes try to write to the same filesystem cache (e.g., node_modules/.cache/webpack) at the same time, they will corrupt the cache files. This leads to bizarre "module not found" errors or segmentation faults.

How to do it:
You do not need to manually create different folders. You just need to set a unique name in your Webpack configuration. Webpack 5 uses this name to create a sub-directory inside the cache folder.

// webpack.legacy.js
module.exports = {
  // ...
  name: 'legacy', // This helps, but cache.name is the specific key
  cache: {
    type: 'filesystem',
    name: 'legacy-build-cache', // Creates: node_modules/.cache/webpack/legacy-build-cache
  },
};

// webpack.modern.js
module.exports = {
  // ...
  name: 'modern',
  cache: {
    type: 'filesystem',
    name: 'modern-build-cache', // Creates: node_modules/.cache/webpack/modern-build-cache
  },
};

---

2. The Build/Output Directory (HIGHLY RECOMMENDED)

You should use separate directories (or distinct naming patterns).
While it is technically possible to write to the same folder if every single file has a unique hash, you face two major risks:

A. The "Clean" Race Condition

Most production builds use CleanWebpackPlugin (or output.clean: true in Webpack 5) to wipe the dist folder before building.

• The Crash: Process A starts and wipes dist. Process A starts writing. Process B starts and wipes dist again, deleting Process A's files while it is still running.
• The Fix: You would have to disable cleaning on one or both builds, which risks leaving stale files from previous deployments.

B. Filename Collisions

If both builds try to output a shared asset (like a font or an image) to the same path (e.g., assets/logo.png), the operating system may lock the file while Process A is writing it, causing Process B to crash when it tries to write the exact same file.

The Safest Architecture:

1. Build to separate temp folders:
   • Legacy $\rightarrow$ dist/legacy
   • Modern $\rightarrow$ dist/modern
2. Merge them at the end:
   Use a final script to copy all files from both folders into the root dist and merge the two manifest JSON files.

Summary Configuration Pattern

Here is how your config structure should look to be 100% safe for parallel execution:

// webpack.base.js (Shared logic)
const path = require('path');

module.exports = (mode) => ({
  // Ensure unique cache name based on the mode (legacy/modern)
  cache: {
    type: 'filesystem',
    name: `${mode}-cache`,
  },
  output: {
    // Ensure unique output folder
    path: path.resolve(__dirname, `dist/${mode}`),
    filename: '[name].[contenthash].js',
    clean: true, // Safe to use because we are in a unique folder!
  },
  plugins: [
    new WebpackAssetsManifest({
      output: 'manifest.json', // Will exist inside dist/legacy/ and dist/modern/
      writeToDisk: true,
    })
  ]
});

Would you like a Node.js script that handles the final step: moving the files from the subfolders to the root dist and merging the two manifest JSONs?

[webdeveric]

@Judahmeek Are you experiencing any issues due to this lib, or is this just a precaution due to the age? As far as I can tell, lockfile is stable and doesn't have any pnpm audit issues. It is getting 2M+ downloads a week so I'd expect any issues to have been identified by now.

I have been meaning to switch to a lib that has more recent activity and is not archived.

proper-lockfile looks to be a suitable replacement for lockfile, but is hasn't had any commits in 5 years. Perhaps it is feature complete and stable so it doesn't need any.

[Judahmeek]

@webdeveric @justin808 and I work together and would not be reporting this issue if it hadn't caused us grief.

We had a client using Node@22, webpack@5.99.8, webpack-assets-manifest@6.2.2 report intermittent manifest file merge failures in production while using the merge: true option

We're confident that lockfile's outdated code results in a race condition.

[webdeveric]

@Judahmeek @justin808 Do you have a minimal reproducible example I can clone? I have a PR that switches to proper-lockfile and it would be great to verify that resolves the issue before I merge it.

[Judahmeek]

The problem with race conditions is that they are intermittent. They don't occur every time & their occurrence frequency rate can be significantly different based on environment. I'm ask the client if they can estimate the occurrence frequency they experienced in production. So far I have had no luck reproducing this race condition in development.