@hyperfrontend/workspace§

Five project tiles joined by the edges of their imports, each with its test task, under the command hf affected -t test. A file in core changes and the change travels every import that leaves core: it arrives at api through a value import and at cli through an import a spec makes, and both tasks light; it fades along the dashed type-only import to types, whose task stays dark; it carries on from api to web. A caption under the graph names the rule at each step, and the count beside selectAffected ends at 3 of 5Five project tiles joined by the edges of their imports, each with its test task, under the command hf affected -t test. A file in core changes and the change travels every import that leaves core: it arrives at api through a value import and at cli through an import a spec makes, and both tasks light; it fades along the dashed type-only import to types, whose task stays dark; it carries on from api to web. A caption under the graph names the rule at each step, and the count beside selectAffected ends at 3 of 5

Runs the tasks of a TypeScript monorepo and releases its packages from a graph of what reaches what.

What is @hyperfrontend/workspace?

@hyperfrontend/workspace is the hf command line for a TypeScript monorepo: it runs a project's tasks, runs only the tasks a change affects, scaffolds libraries and makes them publishable, and versions and publishes them from their commits. A workspace adds executors and generators of its own in TypeScript, listed in a manifest beside the project, with no build step.

It is one small tool a team can read end to end. It keeps no task cache and loads no plugins.

Key Features

  • Affected analysis that explains itself

    every task a change selects or skips carries the rule and the file behind the decision

  • The package lifecycle as targets

    typecheck, test, build, e2e, publish, version-check and version, named once in hf.json

  • Generators that compose

    workspace, library, make-publishable, rename and move, callable by name from a generator of your own

  • Releases from commits

    the version flow reads conventional commits, pins dependents, writes the changelog and commits the bump

  • Lint rules on the graph

    module boundaries, dependency checks and shell command lines, for @hyperfrontend/linter

  • Your own executors and generators

    a TypeScript function and a schema, found through a manifest, run with the same command

Why Use @hyperfrontend/workspace?

Decisions you can read

A CI run that skipped a task says why, by rule and by file, and a lint rule that refuses an import names the constraint. When a selection is wrong, the output names the rule to revisit.

Scaffold to publish in one tool

Generate a library, make it publishable with an e2e project that installs the packed tarball, type check and test it, version it from its commits and publish it, all through targets named once in hf.json.

Extend it in TypeScript

A local executor is a function of its options and the task's context; a local generator is a function of a tree, and composes the packaged generators by name. Both load from source, without a compile step.

Installation

npm install --save-dev @hyperfrontend/workspace

Requires Node.js 24 or later. The peers are optional, so install the ones the workspace uses: @hyperfrontend/testing for the test and e2e executors, @hyperfrontend/linter for the inferred lint target, prettier for the format command and the generators, and jsdom for the browser e2e suites. The type check and the build run on the TypeScript the package itself depends on, so the root may carry whatever TypeScript the editor wants, or none.

Quick Start

In a repository with a root package.json:

npx hf generate workspace
npm install
npx hf generate library my-utils --publishable
npx hf run my-utils:test
npx hf affected -t test

The first command writes hf.json and the base configurations and settles the root manifest (an ES module package, with @types/node among its development dependencies), which the second installs; the third writes a library with its project, manifest, configurations and e2e project; the rest run its tasks. The affected run compares with origin/main, or with main where the repository has no such remote branch, unless --base names another revision. The commands and writing an executor or generator are each one page.

API Overview

EntryWhat it is
@hyperfrontend/workspaceThe contract: the types an executor or generator of your own is written against
/cliThe command line as a function
/runnerExecutors and generators by name; one task, many in order, the affected run
/graphThe workspace graph, its persisted state and the affected analysis
/hooksLoads a workspace's TypeScript from source, for scripts of your own
/lintThe projects rule family and the readers a rule of your own shares with it
/generatorsThe helpers a local generator composes the packaged ones with; one entry per generator beneath it
/executors/build and siblingsOne entry per executor, each with its schema
hfThe command line

Limitations

  • No task cache, local or remote: a task runs every time it is asked for.
  • Target configurations (--configuration) are refused; a target has one shape.
  • The graph reads TypeScript and JavaScript imports; a dependency carried only through another language is counted whole, as a fallback, and reported as such.
  • The affected analysis of a historical range is exact only when the working tree is that range's head.

Compatibility

Runs on

  • Node.js>=24.0.0supported
  • Browsersnot supported
  • Web Workersnot supported
  • Linuxsupported
  • macOSsupported
  • Windowssupported

Ships as

  • ESMTree-shakeable
  • CJSNode and older bundlers
  • CLIhf

Architecture Highlights§

The graph records each import with its kind and the role of the file that drew it, so a spec's import reaches the test target and not the build, a type-only import reaches neither test nor lint, and what cannot be followed precisely is counted whole and reported as such. The architecture guide covers the graph, the runner and how the entries are loaded by name.

API Reference§

View:
Organized by entry point

Module Structure

|

20 modules · 413 total exports

The contract executors and generators are written against: the context an executor runs in, the tree a generator edits, and the configuration both read.

12 int2 type

The workspace's command line as a function: what the `hf` executable runs, and what another command line hands its arguments to.

5 fn5 int1 type4 var

The `build` executor: builds a library into a publishable package with the builder, treating the workspace's own packages as first-party.

1 fn1 int2 var

The `e2e` executor: packs a library's build, installs the tarball into the e2e project that tests it, and runs that project's suites.

4 fn2 int1 type

The `publish` executor: publishes a library's build output to the npm registry, skipping a version already there.

1 fn1 int

The `test` executor: runs a project's suites on Node's built-in test runner, in a process of its own that this entry also serves.

2 fn1 int2 var

The `typecheck` executor: runs the TypeScript compiler over a project's library and spec configurations without emitting files.

1 fn1 int

The `version` executor: versions a project from its conventional commits, pins its dependents to the new version, and commits the bump.

2 fn5 int1 type

The `version-batch` executor: versions every library a change makes due a release, and records the bumps in one commit.

2 fn2 int

The `version-check` executor: compares a project's manifest and changelog with what its commits call for, without writing anything.

1 fn1 int

What the generators are built from, so a workspace's own generators compose the packaged ones on the same tree: JSON, project and template helpers, names and paths, and running by name.

41 fn19 int2 type3 var

The `library` generator: creates a TypeScript library of the workspace, and hands a publishable one to `make-publishable`.

2 fn2 int

The `make-publishable` generator: gives a library the targets, manifest fields, README and e2e project a published package needs.

2 fn2 int1 type

The `move` generator: relocates a project under another directory and brings its names, aliases and references along.

2 fn2 int

The `rename` generator: renames a project and carries the new name into everything that refers to it.

2 fn2 int

The `workspace` generator: writes the root configuration the engine reads into a repository that has none.

1 fn1 int

The owned workspace graph: the projects, files, entries and installed packages a workspace holds, the qualified edges between them, and the project edges Nx would draw.

84 fn59 int21 type18 var

The resolution hook that loads a workspace's TypeScript from source: the path aliases of `tsconfig.base.json`, and extensionless relative imports completed the way the compiler does.

10 fn1 int

The `projects` rule family: lint rules that read the workspace graph, and the readers of a workspace's aliases, project files and module exports that the rules and a workspace's own rules share.

14 fn10 int1 type2 var

The task runner as a library: run one task, plan and run many with their prerequisites, and find the executor or generator a name means.

16 fn24 int5 type1 var

Browse guides filtered to this packageSuggest a guide