@hyperfrontend/workspace
v0.3.1
Published
Runs the tasks of a TypeScript monorepo and releases its packages from a graph of what reaches what.
Maintainers
Readme
Runs the tasks of a TypeScript monorepo and releases its packages from a graph of what reaches what.
• 👉 See documentation • 👉 See guides & tutorials
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
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.
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/workspaceRequires 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 testThe 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
| Entry | What it is |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| @hyperfrontend/workspace | The contract: the types an executor or generator of your own is written against |
| /cli | The command line as a function |
| /runner | Executors and generators by name; one task, many in order, the affected run |
| /graph | The workspace graph, its persisted state and the affected analysis |
| /hooks | Loads a workspace's TypeScript from source, for scripts of your own |
| /lint | The projects rule family and the readers a rule of your own shares with it |
| /generators | The helpers a local generator composes the packaged ones with; one entry per generator beneath it |
| /executors/build and siblings | One entry per executor, each with its schema |
| hf | The 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
Requires Node.js 24 or later. There is no browser build.
| Operating System | Supported | | ---------------- | :-------: | | Linux | ✅ | | macOS | ✅ | | Windows | ✅ |
Output Formats
| Format | File | Tree-Shakeable |
| ------ | ------------ | :------------: |
| ESM | index.mjs | ✅ |
| CJS | index.cjs | ❌ |
| Bin | bin/hf.mjs | ❌ |
Part of hyperfrontend
This library is part of the hyperfrontend monorepo.
