@hyperfrontend/builder/bundle/dedupededupe
Shared-first-party dedupe: an additive post-emit pass that lifts first-party modules inlined into multiple per-entry bundles into shared _shared/<srcPath>/index.<fmt>.js chunks and rewrites each consuming entry to import them. Runs over the already-bundled esm/cjs outputs only, leaving per-entry isolated bundling intact.
hoistSharedFirstParty(...) is the entry point. It only hoists copies that planHoists proves safe — structurally identical, references resolvable, and initialization cycle-free — so the worst case is output identical to the input.
The pass is built from composable stages, each exported for direct use: module attribution (attribute, indexOwners, parseEntry), source reachability (collectReachableSources), chunk planning and extraction (planHoists, renderChunk, resolveModuleRefs), and entry rewriting (rewriteEntry).
Ownership is bounded to modules reachable from the entry points' sources, so a spec-only fixture can never own a name, and reference classification is scope-aware (collectFreeRefs), so a parameter that shadows an owned name never becomes an import edge.
API Reference§
ƒ Functions
Groups an entry's attributable declarations by their owning module.
Declarations whose base name is unowned (a dependency or unexported helper inlined into the bundle) are skipped, leaving them in place.
Declarations whose base name is unowned (a dependency or unexported helper inlined into the bundle) are skipped, leaving them in place.
Parameters
| Name | Type | Description |
|---|---|---|
§parsed | ParsedEntry | A parsed entry bundle. |
§owners | OwnerIndex | The first-party ownership index. |
Example
Attributing an entry's declarations
const byModule = attribute(parseEntry(source, 'esm'), owners)Strips rollup's
$N collision-rename suffix from a local name, yielding the canonical source symbol name.Parameters
| Name | Type | Description |
|---|---|---|
§name | string | A local identifier from an emitted bundle. |
Returns
stringThe base name with any trailing
$digits removed.Example
Undoing a collision rename
baseName('Store$1') // => 'Store'Resolves a hoisted module's chunk file name for a format.
Parameters
| Name | Type | Description |
|---|---|---|
§format | ChunkFormat | Output module format. |
Returns
stringThe per-entry chunk file name (
index.esm.js / index.cjs.js).Example
Naming the CJS chunk
chunkFileName('cjs') // => 'index.cjs.js'Walks the first-party import graph from a library's entry sources and returns every
Both static
.ts module file reachable through relative specifiers. Both static
import / export ... from declarations and string-literal dynamic import() calls are followed. Bare specifiers (dependencies and workspace packages) and non-.ts targets (e.g. imported .json data) are outside the graph, as is any resolution escaping srcRoot. Files a library carries but never imports from an entry point — spec-only fixtures above all — are unreachable by construction, which is what keeps their declarations out of the dedupe ownership index.Parameters
Returns
string[Absolute paths of every reachable source file, entry files included.
Example
Reachable modules of a single-entry library
const files = collectReachableSources(['/abs/libs/foo/src/index.ts'], '/abs/libs/foo/src')Computes a rename-insensitive identity key for a top-level statement.
Two copies of the same source that differ only in rollup's per-entry
Two copies of the same source that differ only in rollup's per-entry
$N collision suffixes compare equal, while genuinely different code never collides: $N is stripped from identifier nodes only, so string literals, comments, numeric tokens, and discriminating member names stay intact.Parameters
Returns
stringThe statement's text with
$N stripped from every identifier node.Example
Stripping a dep-namespace local's collision suffix
fingerprintOf(statement, sourceFile) // 'const x = index_cjs_js.getType();' for both `$1` and `$2` copiesBuilds the first-party ownership index from the runtime symbols each module declares.
When
Both exported and private top-level runtime declarations are indexed, so a module's private helpers hoist alongside the exports that use them. Types-only modules declare no runtime symbols and contribute nothing. A name declared by two different modules is ambiguous and dropped from the index, so the pass can never misattribute it.
When
entryFiles is given, only modules reachable from those entry sources through the first-party import graph are indexed; a file the entries never import — a spec-only fixture above all — can then never own a name, so a bundle declaration merely named like one of its symbols (a tree-shaken JSON key, say) stays unattributed instead of forming a phantom chunk. Without entryFiles the whole <srcRoot>/** tree is scanned. Both exported and private top-level runtime declarations are indexed, so a module's private helpers hoist alongside the exports that use them. Types-only modules declare no runtime symbols and contribute nothing. A name declared by two different modules is ambiguous and dropped from the index, so the pass can never misattribute it.
Parameters
Returns
OwnerIndexThe ownership index.
Example
Indexing only what a library's entries reach
const owners = indexOwners('/abs/libs/foo/src', ['/abs/libs/foo/src/index.ts'])Parses one entry bundle into the structural model the hoist pass consumes.
Classifies every top-level statement as an import binding, a removable runtime declaration, the export surface, or an opaque bare statement. Inline
Classifies every top-level statement as an import binding, a removable runtime declaration, the export surface, or an opaque bare statement. Inline
export-modified declarations are treated as part of the export surface (never removable), so the bundle's published API is never disturbed.Parameters
| Name | Type | Description |
|---|---|---|
§source | string | Raw entry bundle source text. |
§format | ChunkFormat | Module format selecting ESM vs CJS import/export shapes. |
Returns
ParsedEntryThe parsed entry model.
Example
Modeling an ESM entry bundle
const parsed = parseEntry("import { x } from './_dependencies/a/index.esm.js'\nclass C {}", 'esm')Plans which first-party modules can be hoisted into shared chunks.
A module qualifies only when it is inlined into at least two entries, is not entangled with a bare statement, presents structurally identical declarations (rename-insensitive) in a consistent order across every copy, references nothing unresolvable, and (after closure and acyclic peeling) depends only on other hoisted modules through a cycle-free graph. Anything failing these is left inlined, so the worst case equals the unmodified output.
A module qualifies only when it is inlined into at least two entries, is not entangled with a bare statement, presents structurally identical declarations (rename-insensitive) in a consistent order across every copy, references nothing unresolvable, and (after closure and acyclic peeling) depends only on other hoisted modules through a cycle-free graph. Anything failing these is left inlined, so the worst case equals the unmodified output.
Parameters
| Name | Type | Description |
|---|---|---|
§entries | EntryInput[ | Parsed entries with their per-module attribution. |
§owners | OwnerIndex | First-party ownership index. |
Returns
Map<Map from module key to its hoist plan.
Example
Planning hoists for a set of entries
const plan = planHoists(entries, owners)Renders a hoisted module chunk: its resolved imports, the union of its declarations, and an export surface naming each declaration by its base name.
Parameters
| Name | Type | Description |
|---|---|---|
§plan | ChunkPlan | The module's declarations plus resolved import edges. |
§format | ChunkFormat | Output module format. |
Returns
stringThe chunk source text.
Example
Rendering an ESM chunk
const source = renderChunk({ decls, crossImports: [], depImports: [] }, 'esm')§functionresolveModuleRefs(
resolveModuleRefs(
Classifies every free identifier referenced by a module's declarations, partitioning them into cross-module edges, dependency edges, and hard blockers.
Reference collection is scope-aware: a name bound inside a declaration (a function parameter, a hoisted
Reference collection is scope-aware: a name bound inside a declaration (a function parameter, a hoisted
var, a block-scoped local) is never a reference, so a callback parameter that happens to share an owned symbol's name can never fabricate a cross-module import edge. Identifiers the module declares itself are intra-chunk and ignored. A name that is neither owned, nor a dependency binding, nor a top-level entry declaration is a runtime global and needs no import. Cross-module references are always safe to lift because planHoists only keeps an acyclic subset, so every dependency chunk is fully evaluated before its dependent.Parameters
| Name | Type | Description |
|---|---|---|
§decls | EntryDecl[ | The module's canonical declarations. |
§owners | OwnerIndex | First-party ownership index. |
§importBindings | Map< | The consuming entry's import bindings. |
§entryDeclNames | Set< | Every top-level declaration name in the entry. |
§selfModuleKey | string | The module being resolved. |
Returns
ModuleResolutionThe reference resolution.
Example
Resolving a module's references
const resolution = resolveModuleRefs(decls, owners, parsed.importBindings, parsed.declNames, 'events/events')Rewrites an entry bundle to consume hoisted modules from
Splices every hoisted declaration (and its leading comments) out of the entry and prepends an import/
_shared/ chunks instead of inlining them. Splices every hoisted declaration (and its leading comments) out of the entry and prepends an import/
require binding the chunk's base export to the entry's local name, aliasing when rollup renamed the local (foo as foo$1). Only the hoisted symbols the entry still references after splicing are re-imported: a private helper used solely by another hoisted export (e.g. a reducer's handlers, used only by the hoisted rootReducer) is seen as dead against the spliced body and omitted from the import, while the chunk it lives in keeps it. The bundle's export surface is left untouched: surviving spliced names are now supplied by the inserted imports, so the published API is byte-for-byte identical to before.Parameters
| Name | Type | Description |
|---|---|---|
§parsed | ParsedEntry | The parsed entry bundle. |
§hoists | EntryHoist[ | The modules hoisted out of this entry, each with its chunk specifier. |
§format | ChunkFormat | Output module format. |
Returns
stringThe rewritten entry source, or the original source when
hoists is empty.Example
Rewriting an entry to import a shared module
const rewritten = rewriteEntry(parseEntry(source, 'esm'), [{ decls, specifier: './_shared/state/index.esm.js' }], 'esm')◈ Interfaces
Everything needed to render a single module's hoisted chunk.
Properties
A cross-module import edge resolved to a concrete chunk specifier.
Properties
A reference from a module's declarations into another first-party module's hoisted chunk.
Properties
A dependency import edge resolved to a concrete (chunk-relative) specifier.
Properties
§
kind:"default" | "named" | "namespace" | "cjs-namespace" | "cjs-named"Binding shape governing how the import is re-emitted.A reference from a module's declarations into a dependency import the entry already carries.
Properties
A removable top-level runtime declaration in an entry bundle, attributed to its owning first-party module by name.
Properties
§
fingerprint:stringRename-insensitive identity key: $N suffixes stripped from identifier nodes; the raw text is still the chunk-body source.One module's hoist within a single entry: the declarations to splice out and the chunk specifier the entry should import them from.
Properties
One parsed entry bundle paired with its declarations grouped by owning module.
Properties
Aggregate result of the shared-first-party hoist pass.
Properties
A single import binding observed at an entry bundle's top level, retaining enough shape to re-materialize the same edge from a hoisted chunk.
Properties
§
kind:"default" | "named" | "namespace" | "cjs-namespace" | "cjs-named"Shape of the binding, governing how it is re-emitted into a shared chunk.Raw classification of every free identifier a module's declarations reference.
Properties
Ownership index mapping each unambiguously-owned runtime symbol to the first-party module that declares it.
Properties
Structural model of one parsed entry bundle.
◆ Types
A first-party module's path under
src/, without extension and forward-slashed (e.g. events/events, models). Doubles as the directory name the module's hoisted chunk lives under: _shared/<moduleKey>/.type ModuleKey = string