@stackline/dynamic-dedupe

Compatibility-first CommonJS module deduplication for linked and copied dependency trees.

Documentation | npm | Issues | Repository

Current package version: 1.0.3

Why this package?

Compatibility-first CommonJS module deduplication for linked and copied dependency trees. It preserves the small dynamic-dedupe API while making loader restoration, path identity, typing, tests, and release engineering safe for current Node.js projects.

Why It Exists

Node normally caches CommonJS modules by resolved filename. With copied package trees, npm link, or --preserve-symlinks, equivalent files can resolve to different filenames and produce separate singleton instances. This package intercepts a CommonJS extension loader and reuses an earlier exports object when the following values match:

file contents;
basename;
the configured number of immediate parent directory names.

The default depth is two, matching the upstream package.

Compatibility

Item	Value
Package	`@stackline/dynamic-dedupe@1.0.3`
Node.js runtime	`>=12`
CommonJS / primary entry	`./index.js`
ES module entry	`./index.mjs`
Type declarations	`./index.d.ts`

Node.js 12 through 24
CommonJS root and deep imports
ESM configuration facade
TypeScript 3.9 and current TypeScript
npm aliases, copied trees, and --preserve-symlinks
zero runtime dependencies

See the compatibility contract and migration guide. Full interactive documentation is available at alexandro.net.

Installation

Install

npm install @stackline/dynamic-dedupe

For an existing dependency that imports dynamic-dedupe, use an npm alias:

npm install dynamic-dedupe@npm:@stackline/dynamic-dedupe

Usage

Existing CommonJS code does not change:

const dedupe = require('dynamic-dedupe')

dedupe.activate()
const first = require('./workspace-a/common/shared/index.js')
const second = require('./workspace-b/common/shared/index.js')

console.log(first === second) // true when identity inputs match
dedupe.deactivate()

ESM

Named and default ESM imports are provided for projects that configure the hook from an ES module:

import { activate, deactivate } from '@stackline/dynamic-dedupe'
import { createRequire } from 'node:module'

const require = createRequire(import.meta.url)
activate()
const service = require('./linked-service.cjs')
deactivate()

The hook affects CommonJS require() only. It does not intercept native ESM imports. Use package-manager constraints, peer dependencies, import maps, or a dedicated Node loader for native ESM graph control.

Security

This package changes process-wide CommonJS loader state. Activate it during controlled process startup and deactivate it when the behavior is no longer needed. Do not use source equivalence as a security boundary. Review the security policy to report a vulnerability privately.

API Surface

API

`activate(extension?, subdirs?)`

Installs deduplication for an extension. The default extension is .js; the default parent-directory depth is 2. Repeated activation of an active extension is idempotent.

const dedupe = require('@stackline/dynamic-dedupe')

dedupe.activate()         // .js, two parent directories
dedupe.activate('.ts', 3) // after a .ts CommonJS loader is registered

`deactivate(extension?)`

Disables deduplication and restores the exact loader that preceded activation when the Stackline hook is still the outermost hook. If another tool wrapped it later, that tool is left intact and the embedded Stackline hook becomes a pass-through.

`reset()`

Clears dedupe identities recorded by this package. It does not clear Node's require.cache and does not deactivate a loader.

Local Development

git clone https://github.com/alexandroit/stackline-dynamic-dedupe.git
cd stackline-dynamic-dedupe
npm ci
npm run verify

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run test:smoke

Release Checklist

Run npm run verify and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

License

MIT. The original copyright and license are preserved in LICENSE. Attribution and modification details are recorded in NOTICE and THIRD_PARTY_LICENSES.md.

Credits and original authors

Stackline Maintainers.
Thorsten Lorenz.
Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.