@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 — plugin wiring (json, node-resolve, commonjs, typescript, terser), output options, and onwarn suppression — lives entirely inside the worker's job-runner.ts, which 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

Name	Type	Description
§descriptor	`RollupBuildDescriptor`	Build descriptor to dispatch.
§options	`DispatchRollupWorkerOptions`	Worker 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' })

§function

resolveDefaultRollupWorkerPath(workspaceRoot: string): RollupWorkerInvocation

Default worker-path resolution: prefers the built-and-published artifact, falls back to the workspace dist path, and finally to the in-source TypeScript file via @swc-node/register (bootstrap case where builder is building itself for the first time and the dist worker doesn't exist yet).
Looks at, in order:

<workspaceRoot>/dist/libs/builder/bundle/rollup/worker/index.cjs.js
<workspaceRoot>/node_modules/@hyperfrontend/builder/bundle/rollup/worker/index.cjs.js
<workspaceRoot>/libs/builder/src/bundle/rollup/worker/index.ts (with --require \@swc-node/register)

Parameters

Name	Type	Description
§workspaceRoot	`string`	Absolute workspace root.

Returns

RollupWorkerInvocation

Worker invocation descriptor, or undefined if no candidate exists.

Example

Locating the worker for an in-workspace consumer

const invocation = resolveDefaultRollupWorkerPath('/abs/repo')
if (!invocation) throw new Error('builder rollup worker artifact not found')

§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

Name	Type	Description
§job	`RollupBuildDescriptor`	Descriptor 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', ... })

§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

Name	Type	Description
§bin	`BinConfig`	Bin declaration including name, runner, and per-bin bootstrap override.
§context	`BuildContext`	Resolved build context.
§format	`BinScriptFormat`	Format being built (one of `bin.format`'s entries).
§formats	`BinScriptFormat[]`	Full list of formats requested for this bin (drives the CJS filename).
§reportPath	`string`	Absolute 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')

§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

Name	Type	Description
§entry	`EntryPoint`	Entry point to compile.
§config	`CjsConfig`	CJS-format configuration.
§context	`BuildContext`	Resolved build context.
§reportPath	`string`	Absolute 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')

§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

Name	Type	Description
§entry	`EntryPoint`	Entry point to compile.
§config	`EsmConfig`	ESM-format configuration.
§context	`BuildContext`	Resolved build context.
§reportPath	`string`	Absolute 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')

§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

Name	Type	Description
§entry	`EntryPoint`	Entry point to bundle.
§config	`IifeConfig`	IIFE-format configuration.
§context	`BuildContext`	Resolved build context.
§reportPath	`string`	Absolute 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')

§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

Name	Type	Description
§entry	`EntryPoint`	Entry point to bundle.
§config	`UmdConfig`	UMD-format configuration.
§context	`BuildContext`	Resolved build context.
§reportPath	`string`	Absolute 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')

◈ 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?:string—

Override process.execPath for the spawned worker (used by tests).

§label?:string—

Human-readable label for log lines and monitor checkpoints (e.g. esm:./browser).

§monitor?:MemoryMonitor—

Optional memory monitor invoked before and after the spawned worker.

§workerPath:string—

Absolute path to the worker entry script. Required — see resolveDefaultRollupWorkerPath.

§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:RollupWorkerBin—

Bin-output config carried by ESM / CJS descriptors that emit an executable bin. null for non-bin entries.

§bundle:RollupWorkerBundleOutput—

Bundle-output config carried by IIFE / UMD descriptors. null for esm/cjs.

§bundledDepsPlugin:RollupWorkerBundledDepsPlugin—

When set: install the externalize-bundled-deps plugin (esm/cjs only).

§bundleWorkspaceDeps:boolean—

When true, workspace deps are inlined; otherwise treated as external.

§external:string[]—

Pre-resolved external package list.

§format:RollupWorkerFormat—

Output format.

§inputFile:string—

Absolute path to the source TS/JS entry.

§outputDir:string—

Absolute directory the worker writes its output(s) under.

§projectRoot:string—

Absolute project root threaded into the typescript plugin.

§reportPath:string—

Absolute path the worker writes its JSON report to.

§sourcemap:boolean—

Sourcemap toggle threaded into the rollup output.

§tsConfigPath:string—

Absolute tsconfig path threaded into the typescript plugin.

§workspaceRoot:string—

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

§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:string—

Banner string prepended to the output (typically the #!/usr/bin/env node shebang).

§chmod:number—

File 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:string—

Footer string appended to the output (the bootstrap that wires the runner to process.argv).

§inlineDynamicImports:boolean—

When true, dynamic imports are inlined so the bin remains a single self-contained file.

§outputFile:string—

Absolute path the worker writes the bin output to.

§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?:string—

UMD-only AMD module identifier.

§globalName:string—

Global variable name exposed by the bundle.

§globals?:Record<string, string>—

Global names mapped onto the external dependencies.

§minify:boolean—

Emit a minified twin alongside the unminified bundle.

§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:string—

Absolute path to the worker entry script.

§interface

RollupWorkerReport

Memory + size summary written to reportPath when the worker exits cleanly.

Properties

§durationMs:number—

Worker wall-clock duration in ms.

§endHeapMB:number—

process.memoryUsage().heapUsed in MB at end of bundle.

§endRssMB:number—

process.memoryUsage().rss in MB at end of bundle.

§outputSize:number—

Total on-disk size of every emitted output, in bytes.

◆ Types

§type

RollupWorkerFormat

Output format the rollup worker produces.

type RollupWorkerFormat = "esm" | "cjs" | "iife" | "umd"