Webpack Dump Metadata Plugin

0.2.0 · active · verified Tue Apr 21

The `dumpmeta-webpack-plugin` is a Webpack plugin designed to save build-time metadata to a specified file, typically for post-build analysis or integration with other tools. As of its current stable version, 0.2.0, it offers compatibility with Webpack 5. The plugin differentiates itself through its simplicity and a `prepare` option that allows developers to precisely extract and format the desired properties from Webpack's `stats` object before serialization, ensuring only relevant, JSON-serializable data is saved. While release cadence appears infrequent, updates address major Webpack version compatibility. It serves as a focused utility for build introspection rather than a comprehensive reporting tool.

Common errors

```
TypeError: DumpMetaPlugin is not a constructor
```
cause Attempting to import `DumpMetaPlugin` as a default export or incorrectly using `require`.

fix For ES Modules, use `import { DumpMetaPlugin } from 'dumpmeta-webpack-plugin';`. For CommonJS, use `const { DumpMetaPlugin } = require('dumpmeta-webpack-plugin');`.
```
Failed to serialize Webpack metadata: Converting circular structure to JSON
```
cause The `prepare` function returned an object that contains circular references, which JSON.stringify cannot handle.

fix Carefully inspect the object returned by your `prepare` function. Ensure it does not include any properties that recursively refer back to themselves or parent objects. Only extract specific, necessary primitive properties.
```
WebpackError: [dumpmeta-webpack-plugin] Error writing metadata file: EACCES: permission denied, open '/path/to/meta.json'
```
cause The plugin does not have sufficient write permissions to the specified `filename` path.

fix Ensure that the directory where `meta.json` is to be written has appropriate write permissions for the user running the Webpack build. Alternatively, specify a different output `filename` to a writable location.

Warnings

breaking Version 0.2.0 introduced compatibility with Webpack 5. While the plugin itself aims to be backwards compatible, internal changes in Webpack's `stats` object structure between major versions might affect custom `prepare` functions written for older Webpack versions.
Fix: Review and update your `prepare` function logic when migrating to Webpack 5 to ensure it correctly extracts properties from the potentially changed `stats` object structure. Refer to Webpack 5's `stats` documentation.
gotcha The `prepare` option's return value *must* be JSON-serializable. If it returns functions, Promises, or other non-serializable JavaScript objects, the plugin will fail when attempting to write the file.
Fix: Ensure that the object returned by your `prepare` function contains only primitive values, arrays, and plain objects. Transform complex types (e.g., Dates) into serializable formats like ISO strings.
gotcha This plugin is typically a development dependency (`--save-dev`) as it operates during the build process and is not required at runtime in production bundles.
Fix: Install using `npm install dumpmeta-webpack-plugin --save-dev` or `yarn add dumpmeta-webpack-plugin --dev`.

Install

npm install dumpmeta-webpack-plugin npm
yarn add dumpmeta-webpack-plugin yarn
pnpm add dumpmeta-webpack-plugin pnpm

Imports

DumpMetaPlugin

wrong:

const DumpMetaPlugin = require('dumpmeta-webpack-plugin');

correct:

import { DumpMetaPlugin } from 'dumpmeta-webpack-plugin';

For CommonJS environments, use the named require syntax. For ESM, use the named import.

DumpMetaPlugin (CommonJS)
wrong:
```
import DumpMetaPlugin from 'dumpmeta-webpack-plugin';
```
correct:
```
const { DumpMetaPlugin } = require('dumpmeta-webpack-plugin');
```
This is the correct CommonJS syntax for importing the named export. Avoid default import as it's not a default export.
DumpMetaPluginOptions
```
import type { DumpMetaPluginOptions } from 'dumpmeta-webpack-plugin';
```
Used for type-checking the plugin's configuration options in TypeScript projects.

Quickstart

Demonstrates how to configure and use `DumpMetaPlugin` in a `webpack.config.js` to save custom build metadata, including build hash and timestamps, to a `meta.json` file.

import { DumpMetaPlugin } from 'dumpmeta-webpack-plugin';
import path from 'path';

export default {
  mode: 'production',
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  plugins: [
    // ... other webpack plugins ...
    new DumpMetaPlugin({
      filename: 'dist/meta.json', // Specify the output path for the metadata file
      prepare: stats => ({
        // Customize the metadata to save. Ensure data is JSON-serializable.
        hash: stats.hash, // The build hash
        version: stats.version, // Webpack version
        buildTime: new Date().toISOString(), // Timestamp of the build
        modulesCount: stats.compilation.modules.length, // Number of compiled modules
        errors: stats.hasErrors(), // Check if the build had errors
        warnings: stats.hasWarnings() // Check if the build had warnings
      })
    })
  ]
};

view raw JSON →