@hyperfrontend/builder

Composable, vendor-neutral build toolkit for TypeScript libraries, JS bins, and Node SEA native binaries.

What is @hyperfrontend/builder?

@hyperfrontend/builder is a build-time Node.js toolkit that turns a TypeScript source tree into a publishable npm package. From a single declarative config it discovers entry points, resolves externals, bundles each entry in isolation, emits type declarations, synthesizes the output package.json, copies assets, and, optionally, produces JavaScript bins and standalone Node SEA native binaries.

It is vendor-neutral: nothing about a consumer's workspace (package naming, which deps are first-party, hoist policy) is hard-coded. You inject those opinions through predicates and config, so the same toolkit drives a leaf utility library and a multi-entry framework alike.

Key Features

• Multi-format output: emit ESM, CJS, IIFE, and UMD bundles from one config; omit a format to skip it.
• Bins & native binaries: synthesize JavaScript bins and cross-platform Node SEA native executables.
• Per-entry isolation: each entry point bundles independently, keeping peak memory bounded on large graphs.
• Predicate-driven extensibility: classify workspace packages, externals, and assets with plain functions instead of config DSLs.
• Self-contained packages: bundle first-party and third-party dependencies, with an additive post-emit pass that dedups shared internals into _shared/ chunks.
• Composable phases: run the bundle, package, and bin phases together via build, or drive each phase on its own.

Architecture Highlights

• build orchestrates; phases compose. build(config) runs the full pipeline, while runBundlePhase, runPackagePhase, and runBinPhase remain individually callable against a shared BuildContext from createBuildContext.
• Predicate extension model. Externals, workspace membership, and asset conditions are expressed as predicates (byNames, byPrefix, or your own), keeping the core free of workspace-specific assumptions.
• Memory-aware by design. Per-entry bundling plus an opt-in memory monitor (createMemoryMonitor, recover) keep large builds inside constrained environments.

Why Use @hyperfrontend/builder?

Most library bundlers assume one entry point, one format, and a fixed notion of what is "external." @hyperfrontend/builder is built for monorepos that publish many packages with shared internals and varied output needs:

• You need ESM and CJS and CDN-ready bundles from the same source.
• You ship CLIs and want native binaries without standing up a separate SEA pipeline.
• You want bundled, self-contained packages without forcing transitive installs on consumers.
• You want to script the build programmatically (or hand it to the hf-build CLI) without adopting a heavyweight, opinionated framework.

Installation

npm install --save-dev @hyperfrontend/builder

typescript is a required peer dependency: the builder drives declaration emit through your project's TypeScript and is built against TypeScript >= 5.9. Install it alongside the builder if your project does not already depend on it:

npm install --save-dev "typescript@>=5.9"

Quick Start

Drive the full pipeline programmatically with build:

import { build, byPrefix } from '@hyperfrontend/builder'

const result = await build({
  projectRoot: '/abs/path/to/libs/my-lib',
  workspaceRoot: '/abs/path/to/workspace',
  // Treat sibling workspace packages as first-party (bundled), everything else external.
  isWorkspacePackage: byPrefix('@my-scope/'),
  esm: { bundleWorkspaceDeps: true },
  cjs: { bundleWorkspaceDeps: true },
})

console.log(result)

Or build straight from a JSON config with the bundled CLI:

# Reads ./builder.config.json by default
hf-build --config ./builder.config.json --verbose

Need finer control? Compose the phases yourself:

import { createBuildContext, runBundlePhase, runPackagePhase } from '@hyperfrontend/builder'

const ctx = createBuildContext(config)
await runBundlePhase(ctx, config)
await runPackagePhase(ctx, config, /* formats */ [])

API Overview

Export	Description
build	Run the full pipeline (bundle → package → bin) from a BuildConfig.
createBuildContext	Derive the shared BuildContext used by the individual phases.
runBundlePhase	Emit per-entry bundles and declarations for the configured formats.
runPackagePhase	Synthesize the output package.json, assets, and license file.
runBinPhase	Synthesize JavaScript bins and Node SEA native binaries.
createMemoryMonitor / recover	Observe build memory pressure and recover from soft limits.
byNames / byPrefix	Preset predicate factories for classifying packages and externals.

Advanced primitives are available under sub-path entries: for example @hyperfrontend/builder/presets, @hyperfrontend/builder/bundle, @hyperfrontend/builder/package, and @hyperfrontend/builder/bin. See the documentation for the full surface.

Compatibility

@hyperfrontend/builder is a build-time tool that runs on Node.js. It is not intended for browser, Web Worker, or CDN runtimes.

Environment	Supported
Node.js >= 18	✅
npm >= 8	✅
TypeScript >= 5.9	✅
Browser	❌

License

MIT