@hyperfrontend/workspace/executors/build

build

Builds a library into a publishable package with @hyperfrontend/builder, deciding what holds for every workspace: the packages the workspace's own projects carry are first-party (inlined where a format asks, left out of the published dependencies), the repository fields come from the root manifest, third-party licences are collected, and the project's README and changelog travel with the package.

{
  "build": {
    "executor": "@hyperfrontend/workspace:build",
    "options": {
      "esm": { "bundleWorkspaceDeps": false },
      "cjs": { "bundleWorkspaceDeps": false },
      "iife": { "entry": ".", "globalName": "AcmeMyUtils" },
      "rootAssets": ["LICENSE.md"]
    }
  }
}
OptionWhat it does
--outputPathWhere the package is written, relative to the root; defaults to dist/<project root>
--tsConfigThe TypeScript configuration, relative to the root; defaults to tsconfig.lib.json in the project
--rootAssetsFiles at the root copied into the package when they exist; FUNDING.md only into a package that declares funding
--assetsFurther files to copy, each a source directory with file names or a glob and a destination
--externalPackages kept external in every format
--esm, --cjsThe two module formats: entries, source maps, externals, whether workspace or all dependencies are inlined
--iife, --umdThe two browser bundles: the entry, the global name, minification, externals and their globals
--binExecutables to write beside the library from src/bin/<name>.ts, in either module format
--dedupeSharedInternalsHoists first-party modules shared by several entries into one chunk; defaults to true
--cleanEmpties the output directory first, when it is empty or holds a previous build; defaults to true
--verbosePrints the build's diagnostics

Each format is omitted to skip it. The options of a format are the builder's own, and are documented with it.

API Reference§

ƒ Functions

§function

rootAssetSpecs(root: string, names: unknown): AssetSpec[]

The assets copied from the workspace root.
Parameters
NameTypeDescription
§root
stringThe workspace root, absolute
§names
unknownThe files, relative to the root
Returns
AssetSpec[]
One asset spec per file that exists, the funding file conditional on the package declaring funding
Example

A missing file is skipped, the funding file is conditional

rootAssetSpecs('/repo', ['LICENSE', 'FUNDING.md', 'NOTICE'])
// => [
//   { from: '/repo', files: ['LICENSE'] },
//   { from: '/repo', files: ['FUNDING.md'], condition: (manifest) => Boolean(manifest.funding) },
// ] when /repo has no NOTICE

◈ Interfaces

§interface

BuildExecutorOptions

Schema-validated executor options. Mirrors BuildConfig from @hyperfrontend/builder/models minus what the executor decides for every workspace (isWorkspacePackage, filterWorkspaceDepsFromOutput, inheritFieldsFrom, thirdPartyLicenses, memoryMonitor).
Properties
§outputPath?:stringOutput directory, relative to the workspace root. Defaults to dist/<project root>.
§tsConfig?:stringPath to tsconfig, relative to the workspace root. Defaults to <project root>/tsconfig.lib.json.
§rootAssets?:string[]Files at the workspace root copied into the package when they exist, such as a licence. FUNDING.md is copied only into a package that declares funding.
§assets?:AssetSpec[]Additional asset specs to copy in addition to the project's README and changelog and the root assets.
§external?:string[]Global externals applied to every format.
§esm?:EsmConfig | EsmConfig[]ESM output configuration. Omit to skip.
§cjs?:CjsConfig | CjsConfig[]CommonJS output configuration. Omit to skip.
§iife?:IifeConfig | IifeConfig[]IIFE bundle configuration. Omit to skip.
§umd?:UmdConfig | UmdConfig[]UMD bundle configuration. Omit to skip.
§unpkg?:stringOverride path for the unpkg field. Defaults to the first UMD bundle path.
§jsdelivr?:stringOverride path for the jsdelivr field. Defaults to the first UMD bundle path.
§bin?:BinConfig[]Bin declarations to synthesize alongside the library.
§dedupeSharedInternals?:booleanHoist first-party modules shared across entry bundles into _shared/ chunks. Defaults to enabled.
§verbose?:booleanEnable verbose / debug logging.
§clean?:booleanEmpty the output directory before emitting. Defaults to enabled; only an empty directory or a previous build of this package is removed.

● Variables

§type

buildExecutor

Builds a library into a publishable package.
Example

A `build` target writing ESM, CommonJS and a browser bundle

{
  "targets": {
    "build": {
      "executor": "@hyperfrontend/workspace:build",
      "options": {
        "esm": { "bundleWorkspaceDeps": true },
        "cjs": { "bundleWorkspaceDeps": true },
        "umd": { "entry": ".", "globalName": "AcmeCore" },
        "rootAssets": ["LICENSE", "FUNDING.md"]
      }
    }
  }
}
```
Run with `npx hf run lib-core:build`; the package lands in `dist/libs/core` unless `outputPath` says otherwise.
§type

FUNDING_ASSET

The root asset that travels only with a package that declares funding.