@hyperfrontend/builder
v0.7.4
Published
Composable, vendor-neutral build toolkit for TypeScript libraries, JS bins, and Node SEA native binaries.
Downloads
2,081
Maintainers
Readme
Composable, vendor-neutral build toolkit for TypeScript libraries, JS bins, and Node SEA native binaries.
• 👉 See documentation • 👉 See guides & tutorials
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
buildorchestrates; phases compose.build(config)runs the full pipeline, whilerunBundlePhase,runPackagePhase, andrunBinPhaseremain individually callable against a sharedBuildContextfromcreateBuildContext.- 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.
The architecture guide covers the phase pipeline, the per-entry worker model, and the shared-internals dedup pass.
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-buildCLI) without adopting a heavyweight, opinionated framework.
Installation
npm install --save-dev @hyperfrontend/builderThat one install is all a build needs. TypeScript is a regular dependency rather than a peer, so declaration emit runs the compiler the builder itself depends on, and Rollup and its plugins ship inside the package; the published manifest declares no peer dependencies. The manifest declares Node.js 18 and npm 8, and the bundled Rollup plugins declare Node.js 20, so Node.js 20 or later is the recommended runtime.
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 --verboseNeed 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
Import the root for the pipeline, a sub-path to replace one step of it. Entry points are discovered from the src/ layout and published where the source manifest's exports declare them; see discoverEntries.
| Entry | What it is |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| @hyperfrontend/builder | The pipeline: build, the context it resolves, the result it returns |
| /bundle | Entry discovery, externals, per-entry Rollup dispatch, declarations and the shared-internals dedupe, each an entry of its own beneath it |
| /package | The output manifest, assets and third-party licences, each an entry of its own beneath it |
| /bin | JavaScript bins and Node SEA native binaries |
| /memory | The opt-in memory monitor and the between-phases recovery primitive |
| /presets | The predicate factories for classifying workspace packages |
| /models | The types every phase speaks: the config, the context, the result |
| hf-build | The command line, driving the pipeline from a JSON config |
Every config field, phase signature and result type is in the API reference.
Compatibility
@hyperfrontend/builder is a build-time tool for Node.js 18 or later and npm 8 or later; browsers, Web Workers and CDN runtimes are not targets. On Node.js 18 the Rollup worker that hf-build spawns receives the flag it needs for the crypto global; only a direct import of the /bundle/rollup/worker entry on Node.js 18 has to pass --experimental-global-webcrypto itself.
| Operating System | Supported | | ---------------- | :-------: | | Linux | ✅ | | macOS | ✅ | | Windows | ✅ |
Output Formats
| Format | File | Tree-Shakeable |
| ------ | ----------- | :------------: |
| ESM | index.mjs | ✅ |
| CJS | index.cjs | ❌ |
The package installs the hf-build command, and ships Node SEA native binaries alongside it for linux-x64, linux-arm64, darwin-x64, darwin-arm64, and win32-x64.
