HyperFrontend logo
← Back to @hyperfrontend/builder
@hyperfrontend/builder/bundle/rollup

rollup

Rollup driver: per-format descriptor builders and the per-entry forked-worker dispatcher.

Every format is bundled the same way: build a serializable descriptor and hand it to the worker. The descriptor builders (toEsmBuildDescriptor, toCjsBuildDescriptor, toIifeBuildDescriptor, toUmdBuildDescriptor, toBinBuildDescriptor) translate an entry point plus its format config into a RollupBuildDescriptor, validating externals/globals eagerly so the caller fails before a worker is spawned. dispatchRollupWorker forks a child Node process per entry to run that descriptor in isolation (the per-entry boundary that keeps peak memory bounded), or runRollupWorkerJob runs the same descriptor in-process for tests.

The actual Rollup configuration lives entirely inside the worker's job-runner.ts: plugin wiring (json, node-resolve, commonjs, typescript, terser), output options, and onwarn suppression. That file depends only on rollup and the @rollup/plugin-* packages, so it can bootstrap before any workspace package is built.

API Reference§

ƒ Functions

§function

dispatchRollupWorker(descriptor: RollupBuildDescriptor, options: DispatchRollupWorkerOptions): Promise<RollupWorkerReport>

Forks a single rollup worker for the supplied descriptor and waits for it to exit. The caller-provided descriptor's reportPath is overwritten with a temp-dir path created by this function.
Each worker writes a JSON report at the temp path; this function reads it after the child exits and returns the per-job statistics. If the worker exits non-zero or fails to produce a report, the function throws with a label-rich message.
The temp report directory is cleaned up before returning, regardless of success or failure.
Parameters
NameTypeDescription
§descriptor
RollupBuildDescriptorBuild descriptor to dispatch.
§options
DispatchRollupWorkerOptionsWorker path + optional memory monitor.
Returns
Promise<RollupWorkerReport>
Worker report (output size + memory + duration) for the dispatched job.
Example

Dispatching a single ESM build

const report = await dispatchRollupWorker(descriptor, { workerPath: '/abs/dist/.../worker.cjs.js' })
View source →
§function

resolveDefaultRollupWorkerPath(startDir?: string): RollupWorkerInvocation

Resolves the rollup worker by self-locating it beside the running builder module: ascends from the module's own directory to the builder package root and returns the worker at bundle/rollup/worker. This works whether the builder runs from its built dist, an installed node_modules copy, or melded into a host bundle under _dependencies/. The compiled index.cjs.js is preferred; an index.ts sibling resolves with the @swc-node/register loader for source-mode bootstrap.
Parameters
NameTypeDescription
§startDir?
stringDirectory to begin the ascent from. Defaults to the running module's directory; pass an explicit value to resolve from another anchor or under test.
Returns
RollupWorkerInvocation
Worker invocation descriptor, or undefined if no worker is found under any ancestor.
Example

Locating the worker beside the builder

const invocation = resolveDefaultRollupWorkerPath()
if (!invocation) throw new Error('builder rollup worker artifact not found')
View source →
§function

runRollupWorkerJob(job: RollupBuildDescriptor): Promise<RollupWorkerReport>

Runs a single rollup invocation as described by job and writes the resulting report to job.reportPath.
Use this to drive the worker logic in-process; use dispatchRollupWorker to run the same job in a forked Node process.
Parameters
NameTypeDescription
§job
RollupBuildDescriptorDescriptor describing the rollup invocation.
Returns
Promise<RollupWorkerReport>
The on-disk report data the worker would have persisted.
Example

Driving the worker logic in-process for a fixture

const report = await runRollupWorkerJob({ format: 'esm', inputFile: '/abs/in.ts', ... })
View source →
§function

toBinBuildDescriptor(bin: BinConfig, context: BuildContext, format: BinScriptFormat, formats: BinScriptFormat[], reportPath: string): RollupBuildDescriptor

Builds the worker descriptor for a single bin output (one (bin, format) pair).
Bins are self-contained executable scripts: workspace deps are inlined and the worker writes to <outputPath>/bin/<name>.<ext> with the shebang banner, the resolved bootstrap footer, and chmod 0o755 applied.
Output naming convention:
  • ESM: <name>.mjs
  • CJS only: <name>.js
  • CJS alongside ESM: <name>.cjs.js
Parameters
NameTypeDescription
§bin
BinConfigBin declaration including name, runner, and per-bin bootstrap override.
§context
BuildContextResolved build context.
§format
BinScriptFormatFormat being built (one of bin.format's entries).
§formats
BinScriptFormat[]Full list of formats requested for this bin (drives the CJS filename).
§reportPath
stringAbsolute path the worker will write its JSON report to.
Returns
RollupBuildDescriptor
Descriptor ready to be JSON-serialized for the worker.
Example

Producing the descriptor for an `hf-build` CJS bin alongside an ESM twin

const descriptor = toBinBuildDescriptor(bin, context, 'cjs', ['cjs', 'esm'], '/tmp/r.json')
View source →
§function

toCjsBuildDescriptor(entry: EntryPoint, config: CjsConfig, context: BuildContext, reportPath: string): RollupBuildDescriptor

Builds the worker descriptor for the CommonJS output of a single entry point.
Parameters
NameTypeDescription
§entry
EntryPointEntry point to compile.
§config
CjsConfigCJS-format configuration.
§context
BuildContextResolved build context.
§reportPath
stringAbsolute path the worker will write its JSON report to.
Returns
RollupBuildDescriptor
Descriptor ready to be JSON-serialized for the worker.
Example

Producing the descriptor for the root entry

const descriptor = toCjsBuildDescriptor(entry, cjsConfig, context, '/tmp/report.json')
View source →
§function

toEsmBuildDescriptor(entry: EntryPoint, config: EsmConfig, context: BuildContext, reportPath: string): RollupBuildDescriptor

Builds the worker descriptor for the ESM output of a single entry point.
The returned descriptor is fully serializable (no functions), ready to be passed to dispatchRollupWorker.
Parameters
NameTypeDescription
§entry
EntryPointEntry point to compile.
§config
EsmConfigESM-format configuration.
§context
BuildContextResolved build context.
§reportPath
stringAbsolute path the worker will write its JSON report to.
Returns
RollupBuildDescriptor
Descriptor ready to be JSON-serialized for the worker.
Example

Producing the descriptor for the root entry

const descriptor = toEsmBuildDescriptor(entry, esmConfig, context, '/tmp/report.json')
View source →
§function

toIifeBuildDescriptor(entry: EntryPoint, config: IifeConfig, context: BuildContext, reportPath: string): RollupBuildDescriptor

Builds the worker descriptor for an IIFE bundle of a single entry point.
Validates the externals/globals pairing eagerly, throwing before the descriptor is returned.
Parameters
NameTypeDescription
§entry
EntryPointEntry point to bundle.
§config
IifeConfigIIFE-format configuration.
§context
BuildContextResolved build context.
§reportPath
stringAbsolute path the worker will write its JSON report to.
Returns
RollupBuildDescriptor
Descriptor ready to be JSON-serialized for the worker.
Example

Producing the descriptor for an IIFE bundle

const descriptor = toIifeBuildDescriptor(entry, iifeConfig, context, '/tmp/report.json')
View source →
§function

toUmdBuildDescriptor(entry: EntryPoint, config: UmdConfig, context: BuildContext, reportPath: string): RollupBuildDescriptor

Builds the worker descriptor for a UMD bundle of a single entry point.
Validates the externals/globals pairing eagerly, throwing before the descriptor is returned.
Parameters
NameTypeDescription
§entry
EntryPointEntry point to bundle.
§config
UmdConfigUMD-format configuration.
§context
BuildContextResolved build context.
§reportPath
stringAbsolute path the worker will write its JSON report to.
Returns
RollupBuildDescriptor
Descriptor ready to be JSON-serialized for the worker.
Example

Producing the descriptor for a UMD bundle

const descriptor = toUmdBuildDescriptor(entry, umdConfig, context, '/tmp/report.json')
View source →

◈ Interfaces

§interface

DispatchRollupWorkerOptions

Caller-supplied options threaded through dispatchRollupWorker.
Properties
§execArgv?:string[]Extra arguments prepended to the worker invocation (e.g. ['--require', '@swc-node/register']).
§execPath?:stringOverride process.execPath for the spawned worker (used by tests).
§label?:stringHuman-readable label for log lines and monitor checkpoints (e.g. esm:./browser).
§monitor?:MemoryMonitorOptional memory monitor invoked before and after the spawned worker.
§workerPath:stringAbsolute path to the worker entry script. Required; see resolveDefaultRollupWorkerPath.
View source →
§interface

RollupBuildDescriptor

Serializable rollup-build descriptor: the contract between the parent orchestrator and a forked worker. Every field must round-trip through JSON.stringify / JSON.parse: no functions, no class instances.
The worker reconstructs RollupOptions from the descriptor using the same plugin factories the parent would have used in-process.
Properties
§bin:RollupWorkerBinBin-output config carried by ESM / CJS descriptors that emit an executable bin. null for non-bin entries.
§bundle:RollupWorkerBundleOutputBundle-output config carried by IIFE / UMD descriptors. null for esm/cjs.
§bundledDepsPlugin:RollupWorkerBundledDepsPluginWhen set: install the externalize-bundled-deps plugin (esm/cjs only).
§bundleWorkspaceDeps:booleanWhen true, workspace deps are inlined; otherwise treated as external.
§external:string[]Pre-resolved external package list.
§format:RollupWorkerFormatOutput format.
§inputFile:stringAbsolute path to the source TS/JS entry.
§outputDir:stringAbsolute directory the worker writes its output(s) under.
§projectRoot:stringAbsolute project root threaded into the typescript plugin.
§reportPath:stringAbsolute path the worker writes its JSON report to.
§sourcemap:booleanSourcemap toggle threaded into the rollup output.
§tsConfigPath:stringAbsolute tsconfig path threaded into the typescript plugin.
§workspaceRoot:stringAbsolute workspace root threaded into the typescript plugin.
§workspaceRoutes:WorkspaceBundledDepRoute[]Workspace bundled-dep routes consumed by the externalize plugin. When non-empty, imports of these workspace packages (and matching sub-paths) are rerouted to the corresponding _dependencies/<packageName>(/<sub>)?/index.<ext> chunk. Empty array for descriptors that do not opt into workspace-dep hoisting.
View source →
§interface

RollupWorkerBin

Bin-output configuration carried by ESM / CJS descriptors when the entry is a package.json#bin executable script.
When set, the worker writes the bundle to outputFile (instead of the format's default index.<fmt>.js filename), prepends the banner and appends the footer, and applies chmod to the produced file so the npm bin symlink is invokable.
Properties
§banner:stringBanner string prepended to the output (typically the #!/usr/bin/env node shebang).
§chmod:numberFile mode applied via chmodSync after the output is written (e.g. 0o755).
§exports:"none" | "default" | "auto" | "named"Rollup output.exports mode passed through to bundle.write.
§footer:stringFooter string appended to the output (the bootstrap that wires the runner to process.argv).
§inlineDynamicImports:booleanWhen true, dynamic imports are inlined so the bin remains a single self-contained file.
§outputFile:stringAbsolute path the worker writes the bin output to.
View source →
§interface

RollupWorkerBundleOutput

Bundle-output configuration carried by IIFE / UMD descriptors.
Captures the format-specific output knobs the worker needs to reconstruct OutputOptions for a self-contained browser bundle.
Properties
§amdId?:stringUMD-only AMD module identifier.
§globalName:stringGlobal variable name exposed by the bundle.
§globals?:Record<string, string>Global names mapped onto the external dependencies.
§minify:booleanEmit a minified twin alongside the unminified bundle.
View source →
§interface

RollupWorkerInvocation

Resolved worker invocation: absolute path + any extra Node args (e.g. --require \@swc-node/register when the worker is loaded from TypeScript source during a bootstrap build).
Properties
§execArgv:string[]Extra args prepended to the spawned child's argv.
§path:stringAbsolute path to the worker entry script.
View source →
§interface

RollupWorkerReport

Memory + size summary written to reportPath when the worker exits cleanly.
Properties
§durationMs:numberWorker wall-clock duration in ms.
§endHeapMB:numberprocess.memoryUsage().heapUsed in MB at end of bundle.
§endRssMB:numberprocess.memoryUsage().rss in MB at end of bundle.
§outputSize:numberTotal on-disk size of every emitted output, in bytes.
View source →

◆ Types

§type

RollupWorkerFormat

Output format the rollup worker produces.
type RollupWorkerFormat = "esm" | "cjs" | "iife" | "umd"
View source →