@hyperfrontend/builder/models

models

Type definitions for builder configuration, runtime context, and build results.

This entry point re-exports the cross-cutting types consumed by the bundle, package, and bin subdomains: BuildConfig and the per-format configuration shapes (EsmConfig, CjsConfig, IifeConfig, UmdConfig), the BinConfig and SeaConfig declarations, the resolved BuildContext passed to primitives, and the BuildResult returned by the build() facade. Consumers composing builder primitives (or extending it with custom presets) import from here to stay aligned with the shapes the rest of the library expects.

API Reference§

◈ Interfaces

§interface

AssetSpec

Generic asset-copy specification consumed by the package phase.
Either files or glob selects the inputs under from. When neither is provided, every file directly under from is copied.
Properties
§from:stringAbsolute source directory.
§to?:stringOutput subdirectory relative to the build's outputPath; defaults to . (the dist root).
§files?:string[]Explicit relative file names to copy.
§glob?:stringPOSIX-style glob pattern, evaluated relative to from.
§condition?:AssetConditionPredicatePredicate gating whether the spec is materialized.
§interface

AuthorField

Author / contributor entry in package.json.
Properties
§name:stringAuthor name.
§email?:stringAuthor email.
§url?:stringAuthor URL.
§interface

BinConfig

Bin synthesis configuration.
The source file is fixed at src/bin/<name>.ts. The runner export defaults to the file's default export; override with runner to target a named export instead.
Properties
§name:stringBin name (also the package.json#bin key and the source file basename).
§format:BinFormatSpecRequired output format(s) for the bin.
§runner?:stringNamed runner export to bootstrap. Defaults to the file's default export.
§bootstrap?:stringOverride the bootstrap footer template.
§sea?:SeaConfigOpt into Node SEA native binary emission.
§interface

BinOutput

Output record describing a single emitted bin (per format and per platform).
Properties
§name:stringBin name (matches the configured BinConfig.name).
§kind:"cjs" | "esm" | "native"Output kind: a JS script for one of the supported formats, or a native SEA binary.
§outputPath:stringAbsolute path to the emitted artifact.
§platform?:stringNative target identifier (e.g., linux-x64); present only when kind === 'native'.
§interface

BugsField

Bugs field in package.json.
Properties
§url?:stringBug tracker URL.
§email?:stringBug tracker email.
§interface

BuildConfig

Top-level builder configuration consumed by the build() facade.
Properties
§projectRoot:stringAbsolute path to the project being built.
§workspaceRoot:stringAbsolute path to the workspace root.
§outputPath?:stringAbsolute output directory. Defaults to <workspaceRoot>/dist/<projectRelativePath>.
§clean?:booleanEmpty outputPath before emitting, so nothing from an earlier build survives (a stale *.js.map, a chunk for a since-renamed entry). Defaults to true. The clean removes only a directory that is empty or holds a previous build of this package, recognised by the package.json it left behind, and refuses anything else wherever it sits. Set false when several builds, or other tools, accumulate output in one directory. Emitting onto the project's own sources is refused either way.
§tsConfig?:stringPath to the project's tsconfig used for declarations. Defaults to <projectRoot>/tsconfig.lib.json.
§isWorkspacePackage?:IsWorkspacePackagePredicateWorkspace-package predicate; when omitted the bundler treats every dep as external.
§workspaceDepPolicy?:Record<string, WorkspaceDepHoistPolicy>Per-package override of the workspace-dependency hoist policy, keyed by package name. Packages absent from the map default to 'sub-path' (granular, zero-config); set a package to 'whole-surface' to opt into collapsing its sub-paths onto the root chunk. Builder ships no built-in entries; consumers inject their own opinions here, mirroring isWorkspacePackage.
§filterWorkspaceDepsFromOutput?:booleanDrop workspace-internal entries from the output package.json's dependencies.
§inheritFieldsFrom?:InheritFromSpecSelectively copy fields from another package.json onto the output package.json.
§assets?:AssetSpec[]Asset specs to materialize alongside the bundle.
§external?:string[]Global externals applied to every format.
§esm?:EsmConfig | EsmConfig[]ESM configuration; omit to skip ESM output.
§cjs?:CjsConfig | CjsConfig[]CommonJS configuration; omit to skip CJS output.
§iife?:IifeConfig | IifeConfig[]IIFE bundle configuration; omit to skip IIFE output.
§umd?:UmdConfig | UmdConfig[]UMD bundle configuration; omit to skip UMD output.
§unpkg?:stringOverride path for the unpkg field. Defaults to the first UMD bundle path.
§jsdelivr?:stringOverride path for the jsdelivr field. Defaults to the first UMD bundle path.
§bin?:BinConfig[]Bin declarations to synthesize alongside the library.
§files?:string[]Override the published package.json#files allowlist.
When omitted, the allowlist is reflected from the materialized output tree after every emit phase: it names exactly what shipped. Provide an explicit array to take full control of what npm publish ships.
§dedupeSharedInternals?:booleanHoist first-party modules that are inlined into multiple entry bundles into shared _shared/<srcPath>/ chunks and rewrite the entries to import them, removing the duplicated copies. Runs as a safe, additive post-emit pass over the esm/cjs outputs only. Defaults to enabled; set false to keep every entry fully self-contained.
§thirdPartyLicenses?:booleanEmit THIRD_PARTY_LICENSES.md, listing the published dependencies and every third-party package the output inlines, with their license texts. Defaults to emitting it whenever the output inlines third-party code; false never emits it.
§memoryMonitor?:boolean | MemoryMonitorOptionsEnable the memory monitor; pass true for defaults or an options object for custom thresholds.
§verbose?:booleanRaise the build's log level. When true, the shared logger emits at debug (surfacing every phase's progress, timing, and memory diagnostics); when omitted or false, the build stays quiet at error. Also settable via the hf-build --verbose flag.
§interface

BuildContext

Resolved, fully-computed runtime context derived from a BuildConfig.
Unlike BuildConfig, every path and option here has been resolved to an absolute value and every default has been filled in. Builder primitives consume the BuildContext, never the raw config.
Properties
§projectRoot:stringAbsolute path to the project being built.
§workspaceRoot:stringAbsolute path to the workspace root.
§projectRelativePath:stringProject path relative to the workspace root (forward-slash separated).
§outputPath:stringResolved absolute output directory.
§tsConfigPath:stringResolved absolute path to the project's tsconfig.
§external:string[]Global external dependencies to exclude from every bundle.
§assets:AssetSpec[]Asset specs to materialize.
§isWorkspacePackage:IsWorkspacePackagePredicateWorkspace-package predicate, normalized to always-defined.
§entryPointDiscovery:EntryPointDiscoveryResult of the entry-point discovery scan.
§bundledDeps:string[]Third-party deps bundled into _dependencies/<dep>/ and stripped from the output package.json. Empty unless at least one format declares bundleAllDeps.
§workspaceBundledDeps:WorkspaceBundledDep[]Workspace deps bundled into _dependencies/<packageName>(/<sub>)?/. Empty unless at least one format declares bundleAllDeps and the project declares workspace deps.
§startedAt:numberWall-clock timestamp captured at context creation, used for BuildResult.durationMs.
§interface

BuildResult

Final result returned by the build() facade.
Properties
§success:trueWhether the build completed without throwing. Always true when build() resolves.
§formatCounts:FormatCountsPer-format counts of emitted artifacts.
§formatOutputs:FormatOutputsAggregated per-format outputs.
§binOutputs:BinOutput[]Bins emitted (JS scripts and / or native binaries).
§durationMs:numberTotal wall-clock duration in milliseconds.
§interface

BundleAllDepsOptions

Caller overrides to the auto-derived bundled-dep set.
The default set is package.json#dependencies minus peerDependencies minus any package matching isWorkspacePackage. include adds packages absent from dependencies; exclude skips ones that would otherwise be picked up. Neither override can resurrect a peer or workspace package.
Properties
§include?:string[]Force-include packages even if absent from package.json#dependencies.
§exclude?:string[]Skip these packages even if otherwise selected.
§interface

CjsConfig

CommonJS output configuration.
Properties
§entry?:string | string[]Entry pattern(s): exact path, glob, or list. Omit to include all detected entries.
§exclude?:string | string[]Pattern(s) to exclude from the resolved entry set.
§sourcemap?:booleanGenerate sourcemaps. Defaults to false.
§external?:string[]Additional package names to mark external.
§bundleWorkspaceDeps?:booleanInline workspace dependencies (true) or keep them external (false). Defaults to true.
§bundleAllDeps?:boolean | BundleAllDepsOptionsBundle every third-party dep into _dependencies/<dep>/ and route entry imports through that directory at install-relative paths. When true, builder produces a fully self-contained dist with no dependencies field on the published package.
§interface

ConditionalExport

Conditional export specification for the package.json exports field.
Each property maps an export condition (e.g., import, require, types) to a resolved file path, or to a nested conditional-export object for further refinement.
Properties
§import?:stringPath used by ESM import.
§require?:stringPath used by CommonJS require.
§default?:stringDefault fallback path.
§types?:stringTypeScript declaration path.
§node?:string | ConditionalExportNode.js-specific export.
§browser?:string | ConditionalExportBrowser-specific export.
§development?:string | ConditionalExportDevelopment build export.
§production?:string | ConditionalExportProduction build export.
§interface

EntryPoint

A single resolved entry point within a library.
Properties
§exportPath:stringSubpath export key relative to the package root (e.g., ., ./browser, ./browser/v1).
§srcPath:stringPath inside src/ to the entry directory (e.g., `, browser, browser/v1`).
§inputFile:stringAbsolute path to the entry source file (e.g., <projectRoot>/src/<srcPath>/index.ts).
§isRoot:booleanTrue when the entry corresponds to src/index.ts.
§platform?:EntryPointPlatformPlatform hint when the entry lives under src/browser/ or src/node/.
§interface

EntryPointDiscovery

Result of scanning a library for its entry points.
Properties
§category:EntryPointCategoryDetected layout category.
§entryPoints:EntryPoint[]Every discovered entry point in stable order.
§hasRootEntry:booleanWhether src/index.ts exists.
§platformEntries:EntryPoint[]Subset of entries flagged with a platform hint.
§featureEntries:EntryPoint[]Subset of feature / module entries (non-root, non-platform).
§interface

EsmConfig

ESM output configuration.
Properties
§entry?:string | string[]Entry pattern(s): exact path, glob, or list. Omit to include all detected entries.
§exclude?:string | string[]Pattern(s) to exclude from the resolved entry set.
§sourcemap?:booleanGenerate sourcemaps. Defaults to false.
§external?:string[]Additional package names to mark external.
§bundleWorkspaceDeps?:booleanInline workspace dependencies (true) or keep them external (false). Defaults to true.
§bundleAllDeps?:boolean | BundleAllDepsOptionsBundle every third-party dep into _dependencies/<dep>/ and route entry imports through that directory at install-relative paths. When true, builder produces a fully self-contained dist with no dependencies field on the published package.
§interface

FormatCounts

Per-format counts emitted during a build, derived from FormatOutputs.
Properties
§esm:numberNumber of ESM entry points emitted.
§cjs:numberNumber of CommonJS entry points emitted.
§iife:numberNumber of IIFE bundles emitted.
§umd:numberNumber of UMD bundles emitted.
§interface

FormatEntryConfig

Entry-point selection shared by every per-format configuration.
Properties
§entry?:string | string[]Entry pattern(s): exact path, glob, or list. Omit to include all detected entries.
§exclude?:string | string[]Pattern(s) to exclude from the resolved entry set.
§interface

FormatOutputs

Aggregate per-format output collected during the bundle phase.
Properties
§esm:EntryPoint[]ESM entry points emitted.
§cjs:EntryPoint[]CommonJS entry points emitted.
§iife:IifeOutput[]IIFE bundles emitted.
§umd:UmdOutput[]UMD bundles emitted.
§interface

FundingField

Funding entry in package.json.
Properties
§type:stringFunding type (e.g., 'github', 'patreon').
§url:stringFunding URL.
§interface

IifeConfig

IIFE (browser self-executing) output configuration.
A bundle is built from exactly one entry, since every entry would write the same index.iife.js: when entry is omitted the root entry is used, and a selection that resolves to several entries is refused.
Properties
§entry?:string | string[]Entry pattern(s): exact path, glob, or list. Omit to include all detected entries.
§exclude?:string | string[]Pattern(s) to exclude from the resolved entry set.
§globalName:stringGlobal variable name exposed by the bundle.
§minify?:booleanEmit a minified twin alongside the unminified bundle. Defaults to true.
§output?:stringOutput subdirectory relative to outputPath. Defaults to bundle.
§sourcemap?:booleanGenerate sourcemaps. Defaults to false.
§external?:string[]Package names to keep external; if omitted, every dependency is inlined.
§globals?:Record<string, string>Global names for each external dependency. Required when external is set.
§interface

IifeOutput

Build output for a single IIFE bundle.
Properties
§config:IifeConfigResolved IIFE configuration that produced the bundle.
§entries:EntryPoint[]Entry points combined into the bundle.
§interface

InheritFromSpec

Inheritance specification: copy the listed top-level fields from another package.json onto the synthesized output package.json, leaving existing fields intact.
Properties
§from:stringAbsolute path to the source package.json.
§fields:string[]Top-level field names to copy if present on the source.
§interface

MemoryMonitorOptions

Memory-monitor configuration thresholds (in MB).
Properties
§warningMB?:numberHeap-used threshold above which a warning is logged.
§criticalMB?:numberHeap-used threshold above which a critical-level message is logged.
§growthMB?:numberStep-over-step heap growth threshold above which a growth warning is logged.
§interface

PackageJson

Subset of the npm package.json schema that the builder reads from and writes to.
Only fields the builder pipeline interacts with directly are typed; arbitrary additional fields are preserved through the index signature and emitted to the output package.json.
Properties
§name?:stringPackage name.
§version?:stringPackage version.
§description?:stringShort package description.
§license?:stringSPDX license identifier or expression.
§main?:stringMain entry path (CommonJS).
§module?:stringModule entry path (ESM).
§types?:stringTypeScript type-declarations entry path.
§exports?:Record<string, ExportValue>Subpath exports map.
§bin?:string | Record<string, string>Bin name → script path mapping.
§dependencies?:Record<string, string>Runtime dependencies.
§devDependencies?:Record<string, string>Development dependencies.
§peerDependencies?:Record<string, string>Peer dependencies.
§optionalDependencies?:Record<string, string>Optional dependencies.
§repository?:string | RepositoryFieldRepository field.
§bugs?:string | BugsFieldBugs field.
§homepage?:stringHomepage URL.
§author?:string | AuthorFieldAuthor field.
§contributors?:(string | AuthorField)[]Contributors.
§funding?:string | FundingField | FundingField[]Funding entry or list.
§sideEffects?:booleanWhether the package has side effects.
§keywords?:string[]Keywords for npm search.
§unpkg?:stringunpkg CDN entry path.
§jsdelivr?:stringjsdelivr CDN entry path.
§engines?:Record<string, string>Engines compatibility map.
§files?:string[]Files included when packaging.
§interface

RepositoryField

Repository field in package.json.
Properties
§type:stringRepository type (e.g., 'git').
§url:stringRepository URL.
§directory?:stringOptional sub-directory inside the repository.
§interface

SeaConfig

Node SEA (single-executable application) configuration for a bin.
Properties
§platforms:SeaPlatform[]Platforms for which a native binary should be produced.
§interface

UmdConfig

UMD (universal module definition) output configuration.
A bundle is built from exactly one entry, since every entry would write the same index.umd.js: when entry is omitted the root entry is used, and a selection that resolves to several entries is refused.
Properties
§entry?:string | string[]Entry pattern(s): exact path, glob, or list. Omit to include all detected entries.
§exclude?:string | string[]Pattern(s) to exclude from the resolved entry set.
§globalName:stringGlobal variable name exposed by the bundle.
§minify?:booleanEmit a minified twin alongside the unminified bundle. Defaults to true.
§amdId?:stringAMD module identifier. Defaults to the package name.
§output?:stringOutput subdirectory relative to outputPath. Defaults to bundle.
§sourcemap?:booleanGenerate sourcemaps. Defaults to false.
§external?:string[]Package names to keep external; if omitted, every dependency is inlined.
§globals?:Record<string, string>Global names for each external dependency. Required when external is set.
§interface

UmdOutput

Build output for a single UMD bundle.
Properties
§config:UmdConfigResolved UMD configuration that produced the bundle.
§entries:EntryPoint[]Entry points combined into the bundle.
§interface

WorkspaceBundledDep

Per-package workspace dependency to bundle into a hoisted chunk under _dependencies/<packageName>(/<sub>)?.
The default set is package.json#dependencies intersected with the workspace predicate.
Properties
§packageName:stringWorkspace package name (e.g. @hyperfrontend/logging).
§subPath:stringSub-path under the package; '' for the package root.
§specifier:stringPublic import specifier the entry resolves: <packageName> or <packageName>/<subPath>.
§inputPath:stringAbsolute path to the source .ts file resolved via tsconfig path mappings.
§tsConfigPath:stringAbsolute path to the dep's own tsconfig (e.g. tsconfig.lib.json), so the dep is compiled with its own options rather than the consumer project's.
§policy:WorkspaceDepHoistPolicyHoist policy for this dep's chunk(s); see WorkspaceDepHoistPolicy.

◆ Types

§type

AssetConditionPredicate

Predicate gating whether an asset spec materializes for a given package.
type AssetConditionPredicate = (pkg: PackageJson) => boolean
§type

BinFormatSpec

Per-bin format declaration: a single format or an explicit list.
type BinFormatSpec = BinScriptFormat | BinScriptFormat[]
§type

BinScriptFormat

Output formats permitted for a JS bin.
type BinScriptFormat = "cjs" | "esm"
§type

EntryPointCategory

Structural pattern of a library's entry-point layout.
  • root: single entry at src/index.ts
  • platform: browser / node split under src/browser/ and src/node/
  • feature: multiple feature modules under src/<feature>/
  • hybrid: a mix of root, platform, and / or feature entries
  • complex: nested platform-plus-feature structures
type EntryPointCategory = "root" | "platform" | "feature" | "hybrid" | "complex"
§type

EntryPointPlatform

Platform hint used for browser / node-specific entry points.
type EntryPointPlatform = "browser" | "node"
§type

ExportValue

Value form for an exports map entry: a resolved string path, a conditional exports object, or a nested record for sub-conditions.
type ExportValue = string | ConditionalExport | Record<string, unknown>
§type

IsWorkspacePackagePredicate

Predicate identifying packages that are local to the workspace.
Returning true opts the package into workspace-aware behavior such as inlining during bundling or stripping from the published dependencies map.
type IsWorkspacePackagePredicate = (name: string) => boolean
§type

SeaPlatform

Native binary platform identifier in the form <process.platform>-<process.arch>.
type SeaPlatform = "linux-x64" | "linux-arm64" | "darwin-x64" | "darwin-arm64" | "win32-x64"
§type

WorkspaceDepHoistPolicy

Per-package hoist policy for a bundled workspace dependency.
'sub-path' (the zero-config default) gives every public tsconfig specifier of the dep (root and each sub-path) its own _dependencies/<name>(/<sub>)?/index.<ext> chunk, preserving sub-module tree-shaking and reuse, and supporting subpath-only packages that expose no root export. 'whole-surface' is an explicit opt-in collapse: it routes every import of the dep onto a single root chunk, and therefore requires the dep to expose a root export.
type WorkspaceDepHoistPolicy = "sub-path" | "whole-surface"