@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

§condition?:AssetConditionPredicate—

Predicate gating whether the spec is materialized.

§files?:string[]—

Explicit relative file names to copy.

§from:string—

Absolute source directory.

§glob?:string—

POSIX-style glob pattern, evaluated relative to from.

§to?:string—

Output subdirectory relative to the build's outputPath; defaults to . (the dist root).

§interface

AuthorField

Author / contributor entry in package.json.

Properties

§email?:string—

Author email.

§name:string—

Author name.

§url?:string—

Author 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

§bootstrap?:string—

Override the bootstrap footer template.

§format:BinFormatSpec—

Required output format(s) for the bin.

§name:string—

Bin name (also the package.json#bin key and the source file basename).

§runner?:string—

Named runner export to bootstrap. Defaults to the file's default export.

§sea?:SeaConfig—

Opt into Node SEA native binary emission.

§interface

BinOutput

Output record describing a single emitted bin (per format and per platform).

Properties

§kind:"cjs" | "esm" | "native"—

Output kind: a JS script for one of the supported formats, or a native SEA binary.

§name:string—

Bin name (matches the configured BinConfig.name).

§outputPath:string—

Absolute path to the emitted artifact.

§platform?:string—

Native target identifier (e.g., linux-x64); present only when kind === 'native'.

§interface

BugsField

Bugs field in package.json.

Properties

§email?:string—

Bug tracker email.

§url?:string—

Bug tracker URL.

§interface

BuildConfig

Top-level builder configuration consumed by the build() facade.

Properties

§assets?:AssetSpec[]—

Asset specs to materialize alongside the bundle.

§bin?:BinConfig[]—

Bin declarations to synthesize alongside the library.

§cjs?:CjsConfig | CjsConfig[]—

CommonJS configuration; omit to skip CJS output.

§dedupeSharedInternals?:boolean—

Hoist 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.

§esm?:EsmConfig | EsmConfig[]—

ESM configuration; omit to skip ESM output.

§external?:string[]—

Global externals applied to every format.

§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.

§filterWorkspaceDepsFromOutput?:boolean—

Drop workspace-internal entries from the output package.json's dependencies.

§iife?:IifeConfig | IifeConfig[]—

IIFE bundle configuration; omit to skip IIFE output.

§inheritFieldsFrom?:InheritFromSpec—

Selectively copy fields from another package.json onto the output package.json.

§isWorkspacePackage?:IsWorkspacePackagePredicate—

Workspace-package predicate; when omitted the bundler treats every dep as external.

§jsdelivr?:string—

Override path for the jsdelivr field. Defaults to the first UMD bundle path.

§memoryMonitor?:boolean | MemoryMonitorOptions—

Enable the memory monitor; pass true for defaults or an options object for custom thresholds.

§outputPath?:string—

Absolute output directory. Defaults to <workspaceRoot>/dist/<projectRelativePath>.

§projectRoot:string—

Absolute path to the project being built.

§thirdPartyLicenses?:boolean—

Emit a third-party-licenses file.

§tsConfig?:string—

Path to the project's tsconfig used for declarations. Defaults to <projectRoot>/tsconfig.lib.json.

§umd?:UmdConfig | UmdConfig[]—

UMD bundle configuration; omit to skip UMD output.

§unpkg?:string—

Override path for the unpkg field. Defaults to the first UMD bundle path.

§verbose?:boolean—

Raise 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.

§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.

§workspaceRoot:string—

Absolute path to the workspace root.

§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

§assets:AssetSpec[]—

Asset specs to materialize.

§bundledDeps:string[]—

Third-party deps bundled into _dependencies/<dep>/ and stripped from the output package.json. Empty unless at least one format declares bundleAllDeps.

§entryPointDiscovery:EntryPointDiscovery—

Result of the entry-point discovery scan.

§external:string[]—

Global external dependencies to exclude from every bundle.

§isWorkspacePackage:IsWorkspacePackagePredicate—

Workspace-package predicate, normalized to always-defined.

§outputPath:string—

Resolved absolute output directory.

§projectRelativePath:string—

Project path relative to the workspace root (forward-slash separated).

§projectRoot:string—

Absolute path to the project being built.

§startedAt:number—

Wall-clock timestamp captured at context creation, used for BuildResult.durationMs.

§tsConfigPath:string—

Resolved absolute path to the project's tsconfig.

§workspaceBundledDeps:WorkspaceBundledDep[]—

Workspace deps bundled into _dependencies/<packageName>(/<sub>)?/. Empty unless at least one format declares bundleAllDeps and the project declares workspace deps.

§workspaceRoot:string—

Absolute path to the workspace root.

§interface

BuildResult

Final result returned by the build() facade.

Properties

§binOutputs:BinOutput[]—

Bins emitted (JS scripts and / or native binaries).

§durationMs:number—

Total wall-clock duration in milliseconds.

§formatCounts:FormatCounts—

Per-format counts of emitted artifacts.

§formatOutputs:FormatOutputs—

Aggregated per-format outputs.

§success:true—

Whether the build completed without throwing. Always true when build() resolves.

§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

§exclude?:string[]—

Skip these packages even if otherwise selected.

§include?:string[]—

Force-include packages even if absent from package.json#dependencies.

§interface

CjsConfig

CommonJS output configuration.

Properties

§bundleAllDeps?:boolean | BundleAllDepsOptions—

Bundle 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.

§bundleWorkspaceDeps?:boolean—

Inline workspace dependencies (true) or keep them external (false). Defaults to true.

§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.

§external?:string[]—

Additional package names to mark external.

§sourcemap?:boolean—

Generate sourcemaps. Defaults to false.

§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

§browser?:string | ConditionalExport—

Browser-specific export.

§default?:string—

Default fallback path.

§development?:string | ConditionalExport—

Development build export.

§import?:string—

Path used by ESM import.

§node?:string | ConditionalExport—

Node.js-specific export.

§production?:string | ConditionalExport—

Production build export.

§require?:string—

Path used by CommonJS require.

§types?:string—

TypeScript declaration path.

§interface

EntryPoint

A single resolved entry point within a library.

Properties

§exportPath:string—

Subpath export key relative to the package root (e.g., ., ./browser, ./browser/v1).

§inputFile:string—

Absolute path to the entry source file (e.g., <projectRoot>/src/<srcPath>/index.ts).

§isRoot:boolean—

True when the entry corresponds to src/index.ts.

§platform?:EntryPointPlatform—

Platform hint when the entry lives under src/browser/ or src/node/.

§srcPath:string—

Path inside src/ to the entry directory (e.g., `, browser, browser/v1`).

§interface

EntryPointDiscovery

Result of scanning a library for its entry points.

Properties

§category:EntryPointCategory—

Detected layout category.

§entryPoints:EntryPoint[]—

Every discovered entry point in stable order.

§featureEntries:EntryPoint[]—

Subset of feature / module entries (non-root, non-platform).

§hasRootEntry:boolean—

Whether src/index.ts exists.

§platformEntries:EntryPoint[]—

Subset of entries flagged with a platform hint.

§interface

EsmConfig

ESM output configuration.

Properties

§bundleAllDeps?:boolean | BundleAllDepsOptions—

§bundleWorkspaceDeps?:boolean—

Inline workspace dependencies (true) or keep them external (false). Defaults to true.

§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.

§external?:string[]—

Additional package names to mark external.

§sourcemap?:boolean—

Generate sourcemaps. Defaults to false.

§interface

FormatCounts

Per-format counts emitted during a build, derived from FormatOutputs.

Properties

§cjs:number—

Number of CommonJS entry points emitted.

§esm:number—

Number of ESM entry points emitted.

§iife:number—

Number of IIFE bundles emitted.

§umd:number—

Number 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

§cjs:EntryPoint[]—

CommonJS entry points emitted.

§esm:EntryPoint[]—

ESM entry points emitted.

§iife:IifeOutput[]—

IIFE bundles emitted.

§umd:UmdOutput[]—

UMD bundles emitted.

§interface

FundingField

Funding entry in package.json.

Properties

§type:string—

Funding type (e.g., 'github', 'patreon').

§url:string—

Funding URL.

§interface

IifeConfig

IIFE (browser self-executing) 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.

§external?:string[]—

Package names to keep external; if omitted, every dependency is inlined.

§globalName:string—

Global variable name exposed by the bundle.

§globals?:Record<string, string>—

Global names for each external dependency. Required when external is set.

§minify?:boolean—

Emit a minified twin alongside the unminified bundle. Defaults to true.

§output?:string—

Output subdirectory relative to outputPath. Defaults to bundle.

§sourcemap?:boolean—

Generate sourcemaps. Defaults to false.

§interface

IifeOutput

Build output for a single IIFE bundle.

Properties

§config:IifeConfig—

Resolved 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

§fields:string[]—

Top-level field names to copy if present on the source.

§from:string—

Absolute path to the source package.json.

§interface

MemoryMonitorOptions

Memory-monitor configuration thresholds (in MB).

Properties

§criticalMB?:number—

Heap-used threshold above which a critical-level message is logged.

§growthMB?:number—

Step-over-step heap growth threshold above which a growth warning is logged.

§warningMB?:number—

Heap-used threshold above which a 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

§author?:string | AuthorField—

Author field.

§bin?:string | Record<string, string>—

Bin name → script path mapping.

§bugs?:string | BugsField—

Bugs field.

§contributors?:(string | AuthorField)[]—

Contributors.

§dependencies?:Record<string, string>—

Runtime dependencies.

§description?:string—

Short package description.

§devDependencies?:Record<string, string>—

Development dependencies.

§engines?:Record<string, string>—

Engines compatibility map.

§exports?:Record<string, ExportValue>—

Subpath exports map.

§files?:string[]—

Files included when packaging.

§funding?:string | FundingField | FundingField[]—

Funding entry or list.

§homepage?:string—

Homepage URL.

§jsdelivr?:string—

jsdelivr CDN entry path.

§keywords?:string[]—

Keywords for npm search.

§license?:string—

SPDX license identifier or expression.

§main?:string—

Main entry path (CommonJS).

§module?:string—

Module entry path (ESM).

§name?:string—

Package name.

§optionalDependencies?:Record<string, string>—

Optional dependencies.

§peerDependencies?:Record<string, string>—

Peer dependencies.

§repository?:string | RepositoryField—

Repository field.

§sideEffects?:boolean—

Whether the package has side effects.

§types?:string—

TypeScript type-declarations entry path.

§unpkg?:string—

unpkg CDN entry path.

§version?:string—

Package version.

§interface

RepositoryField

Repository field in package.json.

Properties

§directory?:string—

Optional sub-directory inside the repository.

§type:string—

Repository type (e.g., 'git').

§url:string—

Repository URL.

§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.

Properties

§amdId?:string—

AMD module identifier. Defaults to the package name.

§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.

§external?:string[]—

Package names to keep external; if omitted, every dependency is inlined.

§globalName:string—

Global variable name exposed by the bundle.

§globals?:Record<string, string>—

Global names for each external dependency. Required when external is set.

§minify?:boolean—

Emit a minified twin alongside the unminified bundle. Defaults to true.

§output?:string—

Output subdirectory relative to outputPath. Defaults to bundle.

§sourcemap?:boolean—

Generate sourcemaps. Defaults to false.

§interface

UmdOutput

Build output for a single UMD bundle.

Properties

§config:UmdConfig—

Resolved 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

§inputPath:string—

Absolute path to the source .ts file resolved via tsconfig path mappings.

§packageName:string—

Workspace package name (e.g. @hyperfrontend/logging).

§policy:WorkspaceDepHoistPolicy—

Hoist policy for this dep's chunk(s); see WorkspaceDepHoistPolicy.

§specifier:string—

Public import specifier the entry resolves: <packageName> or <packageName>/<subPath>.

§subPath:string—

Sub-path under the package; '' for the package root.

§tsConfigPath:string—

Absolute 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.

◆ 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"