@hyperfrontend/builder/bundle/rolluprollup
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.
Only the /bundle/rollup/worker entry exports runRollupWorkerJob. This entry stays free of the worker's plugin graph, so importing it loads neither the terser plugin nor the crypto global that plugin reads.
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
dispatchRollupWorker( descriptor: RollupBuildDescriptor, options: DispatchRollupWorkerOptions): Promise< RollupWorkerReport>
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>Example
Dispatching a single ESM build
const report = await dispatchRollupWorker(descriptor, { workerPath: '/abs/dist/.../worker.cjs' })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 is preferred; an index.ts sibling resolves with the @swc-node/register loader for source-mode bootstrap.Parameters
| Name | Type | Description |
|---|---|---|
§startDir? | string | Directory 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
RollupWorkerInvocationundefined 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')toBinBuildDescriptor( bin: BinConfig, context: BuildContext, format: BinScriptFormat, formats: BinScriptFormat[ ], reportPath: string): RollupBuildDescriptor
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
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
RollupBuildDescriptorExample
Producing the descriptor for an `hf-build` CJS bin alongside an ESM twin
const descriptor = toBinBuildDescriptor(bin, context, 'cjs', ['cjs', 'esm'], '/tmp/r.json')toCjsBuildDescriptor( entry: EntryPoint, config: CjsConfig, context: BuildContext, reportPath: string): RollupBuildDescriptor
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
RollupBuildDescriptorExample
Producing the descriptor for the root entry
const descriptor = toCjsBuildDescriptor(entry, cjsConfig, context, '/tmp/report.json')toEsmBuildDescriptor( entry: EntryPoint, config: EsmConfig, context: BuildContext, reportPath: string): RollupBuildDescriptor
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
RollupBuildDescriptorExample
Producing the descriptor for the root entry
const descriptor = toEsmBuildDescriptor(entry, esmConfig, context, '/tmp/report.json')toIifeBuildDescriptor( entry: EntryPoint, config: IifeConfig, context: BuildContext, reportPath: string): RollupBuildDescriptor
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
RollupBuildDescriptorExample
Producing the descriptor for an IIFE bundle
const descriptor = toIifeBuildDescriptor(entry, iifeConfig, context, '/tmp/report.json')toUmdBuildDescriptor( entry: EntryPoint, config: UmdConfig, context: BuildContext, reportPath: string): RollupBuildDescriptor
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
RollupBuildDescriptorExample
Producing the descriptor for a UMD bundle
const descriptor = toUmdBuildDescriptor(entry, umdConfig, context, '/tmp/report.json')◈ Interfaces
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
bundledDepsPlugin:RollupWorkerBundledDepsPluginWhen set: install the externalize-bundled-deps plugin (esm/cjs only).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.bundle:RollupWorkerBundleOutputBundle-output config carried by IIFE / UMD descriptors. null for esm/cjs.bin:RollupWorkerBinBin-output config carried by ESM / CJS descriptors that emit an executable bin. null for non-bin entries.package.json#bin executable script. When set, the worker writes the bundle to outputFile (instead of the format's default
index.mjs / index.cjs filename), prepends the banner and appends the footer, and applies chmod to the produced file so the npm bin symlink is invokable.Captures the format-specific output knobs the worker needs to reconstruct
OutputOptions for a self-contained browser bundle.Properties
--require \@swc-node/register when the worker is loaded from TypeScript source during a bootstrap build).Properties
reportPath when the worker exits cleanly.Properties
◆ Types
type RollupWorkerFormat = "esm" | "cjs" | "iife" | "umd"