@hyperfrontend/builder/bundle/externals

externals

Externals resolution primitives: package.json scanning and globals validation for IIFE / UMD bundles.

resolveExternals({ packageJsonPath, additional, isWorkspacePackage, bundleWorkspaceDeps }) reads the project's package.json and combines its dependencies, peerDependencies, and the caller-supplied additional list into a sorted, de-duplicated external list, stripping workspace-internal entries when bundleWorkspaceDeps is true. validateExternalsConfig(external, globals) fails fast when an IIFE / UMD bundle declares an external package without a corresponding global variable name.

API Reference§

ƒ Functions

§function

resolveExternals(options: ResolveExternalsOptions): string[]

Resolves the external package list for a single bundle.
The output combines:

top-level dependencies from the project's package.json
peerDependencies (always external regardless of bundleWorkspaceDeps)
the caller-supplied additional list

When bundleWorkspaceDeps is true and a workspace predicate is supplied, packages matching the predicate are stripped from dependencies and additional so they get inlined by the bundler. Peer dependencies are always preserved.

Parameters

Name	Type	Description
§options	`ResolveExternalsOptions`	Inputs controlling the resolution.

Returns

string[]

Sorted, de-duplicated list of external package names.

Example

Resolving externals while inlining workspace deps

const external = resolveExternals({
  packageJsonPath: '/abs/libs/foo/package.json',
  isWorkspacePackage: (n) => n.startsWith('@hyperfrontend/'),
  bundleWorkspaceDeps: true,
})

View source →

§function

validateExternalsConfig(external: string[], globals: Record<string, string>): void

Verifies that every external dependency declared for an IIFE / UMD bundle has a corresponding entry in the supplied globals map.
Throws an aggregated error listing the missing entries when the configuration is incomplete; resolves silently otherwise.

Parameters

Name	Type	Description
§external	`string[]`	Package names declared as external for the bundle.
§globals	`Record<string, string>`	Mapping of package name to global variable name.

Example

Failing fast when a globals mapping is missing

validateExternalsConfig(['react'], { 'react-dom': 'ReactDOM' })
// => throws: Missing globals mapping for external dependencies: react

View source →

◈ Interfaces

§interface

ResolveExternalsOptions

Inputs to resolveExternals.

Properties

§additional?:string[]Additional package names to mark external regardless of the package.json contents.

§bundledDeps?:string[]Third-party package names being bundled into _dependencies/. When non-empty, these are removed from the resolved external list so their imports are routed to the bundled copies instead of left external.

§bundleWorkspaceDeps?:booleanWhen true, workspace packages are inlined and stripped from the resolved external list.

§isWorkspacePackage?:IsWorkspacePackagePredicatePredicate identifying workspace-internal packages. Defaults to "everything is external".

§packageJsonPath:stringAbsolute path to the project's package.json.

§workspaceBundledDepNames?:string[]Workspace package names being bundled into _dependencies/. When non-empty, these are removed from the resolved external list so their imports are routed to the bundled copies instead of left external.

View source →