pack-config-diff

0.1.0 verified Sat Apr 25 auth: no javascript

Semantic configuration differ and dumper for webpack and rspack projects. Version 0.1.0 (initial public release) supports comparing two configuration objects with semantic explanations, exporting live configs to YAML/JSON/inspect, and generating reports in summary, markdown, or JSON formats. Extracted from Shakapacker and battle-tested in production. Key differentiators: plugin-aware comparison, rule-matching by test pattern, ignore-paths filtering, and support for JS/TS/JSON/YAML config files. Requires Node >=16 and ts-node >=10 as peer dependency. Ships TypeScript types.

Common errors

error Error: Cannot find module 'pack-config-diff' ↓

cause Using CommonJS require() for an ESM-only package.

fix

Use import statement or dynamic import: import packConfigDiff from 'pack-config-diff' or const packConfigDiff = await import('pack-config-diff')

error TypeError: (0 , pack_config_diff.diff) is not a function ↓

cause Using default import destructuring incorrectly; diff is not a property of the default export, it's a named export.

fix

Use named import: import { diff } from 'pack-config-diff'

error Error: Unknown argument: --format=summary ↓

cause The format option must be one of: 'text' (default), 'json', 'markdown'. 'summary' is not supported.

fix

Use --format=text for a human-readable summary, or --format=json / --format=markdown for structured output.

error Error: Config file not found: webpack.config.ts (ts-node peer dependency missing) ↓

cause ts-node >=10 is required to load TypeScript config files, but it is not installed.

fix

Install ts-node as a devDependency: npm install -D ts-node@10

Warnings

gotcha Dump output may include sensitive values (e.g., API keys, secrets) unless --clean is used. ↓

fix Always use --clean flag when sharing dump snapshots. For internal trusted automation, add --no-warn-sensitive to suppress the warning.

gotcha Plugin-aware comparison (--plugin-aware) may produce inaccurate diffs if plugins use non-deterministic serialization or depend on environment variables. ↓

fix Use --plugin-aware only when comparing configs with identical plugin instances and deterministic plugin constructors. For most cases, omit this flag or compare using --ignore-paths='plugins'.

breaking Breaking change in v0.1.0: Package is ESM-only. CommonJS require() will throw a MODULE_NOT_FOUND error if used without dynamic import or --experimental-modules. ↓

fix Convert your code to ES modules (use import) or use dynamic import: const packConfigDiff = await import('pack-config-diff'). Use Node >=16.

deprecated The --mode argument defaults to 'production' if not provided. Using --mode=development or --mode=none is recommended during debugging to avoid unnecessary optimizations masking diff differences. ↓

fix Always specify --mode explicitly when calling diff or dump to ensure consistent comparison conditions.

Install

npm install pack-config-diff

yarn add pack-config-diff

pnpm add pack-config-diff

Imports

default
wrong
```
const packConfigDiff = require('pack-config-diff')
```
correct
```
import packConfigDiff from 'pack-config-diff'
```
Package is ESM-only by default; CommonJS require() will fail in Node >=16 unless using --experimental-modules or dynamic import.
diff
wrong
```
const diff = require('pack-config-diff/diff')
```
correct
```
import { diff } from 'pack-config-diff'
```
Named export 'diff' is available from the main entry. Do not use subpath imports; they are not guaranteed stable.
dump
wrong
```
const { dump } = require('pack-config-diff').default
```
correct
```
import { dump } from 'pack-config-diff'
```
Both 'diff' and 'dump' are named exports. The package also exports a default object with these methods, but named imports are preferred for tree-shaking.
type ConfigDiffOptions
wrong
```
import { ConfigDiffOptions } from 'pack-config-diff'
```
correct
```
import type { ConfigDiffOptions } from 'pack-config-diff'
```
Type imports should use the 'type' keyword for transpile-only usage. ConfigDiffOptions is a TypeScript type, not a runtime value.

Quickstart

CLI command compare two webpack/rspack config files in JSON format, and programmatic API to diff configuration objects with markdown output.

#!/usr/bin/env node
import { execSync } from 'child_process';

// Compare two config files using the CLI
const result = execSync(
  `npx pack-config-diff --left=webpack.dev.js --right=webpack.prod.js --format=json`,
  { encoding: 'utf-8' }
);
console.log(JSON.parse(result));

// Or programmatically
import { diff } from 'pack-config-diff';
import webpack from 'webpack';

const devConfig = webpack({ mode: 'development' });
const prodConfig = webpack({ mode: 'production' });

const report = diff(devConfig, prodConfig, {
  format: 'markdown',
  pluginAware: true,
});
console.log(report);