How to add your own executor and generator to a workspace
You will be able to run a check of your own as a target (npx hf run <project>:<target>) and scaffold your team's kind of project with npx hf generate <name>, both written in TypeScript inside the repository, with no build step and no package to publish.
The packaged executors cover typecheck, test, build, e2e, publish and versioning. Anything particular to your repository (a size budget, a license scan, a service layout) belongs in a project of your own that @hyperfrontend/workspace finds by name.
The examples add a size-budget executor and a service generator to a project at tools/.
1. Declare the project that provides them
A package.json names the project's package and points at two manifests:
{
"name": "@acme/tools",
"private": true,
"executors": "./executors.json",
"generators": "./generators.json"
}
A target names an executor as <package>:<name>, so this project's executors are @acme/tools:<name>. A workspace project with that package name wins over an installed package of the same name.
2. Write the executor
List it in executors.json:
{
"executors": {
"size-budget": {
"implementation": "./src/size-budget",
"schema": "./src/size-budget.json",
"description": "Fail when a built file is larger than its budget."
}
}
}
Describe its options in the schema. A default here is applied before the executor runs:
{
"type": "object",
"properties": {
"file": {
"type": "string",
"description": "The built file, relative to the workspace root"
},
"maxBytes": {
"type": "number",
"default": 10000,
"description": "The largest size allowed"
}
},
"required": ["file"]
}
Then the module, typed as an Executor. It receives its options and an ExecutorContext carrying the workspace root, the project and target names, and every project of the workspace. It reports success or failure:
import type { Executor } from '@hyperfrontend/workspace'
import { statSync } from 'node:fs'
import { join } from 'node:path'
interface SizeBudgetOptions {
file: string
maxBytes: number
}
const sizeBudget: Executor<SizeBudgetOptions> = (options, context) => {
const { size } = statSync(join(context.root, options.file))
const verdict = size <= options.maxBytes ? 'within' : 'over'
process.stdout.write(`${context.projectName}: ${options.file} is ${size} bytes, ${verdict} its budget of ${options.maxBytes}\n`)
return { success: size <= options.maxBytes }
}
export default sizeBudget
3. Give a project the target
In the project.json of the project to check:
{
"targets": {
"size": {
"executor": "@acme/tools:size-budget",
"dependsOn": ["build"],
"options": { "file": "dist/libs/format/index.mjs", "maxBytes": 2000 }
}
}
}
To name the executor for every project at once, put the target under targetDefaults in hf.json instead.
4. Run it
npx hf run format:size
format: dist/libs/format/index.mjs is 348 bytes, within its budget of 2000
An option after the task overrides the configured one, read as the type the schema declares:
npx hf run format:size --maxBytes=100
The task now exits 1, so run-many and affected skip whatever depends on it.
5. Write the generator
List it in generators.json:
{
"generators": {
"service": {
"factory": "./src/service",
"schema": "./src/service.json",
"description": "A library under services/, tagged as a service, with a first module."
}
}
}
The schema takes the name as the first positional argument:
{
"type": "object",
"properties": {
"name": { "type": "string", "": { "$source": "argv", "index": 0 } }
},
"required": ["name"]
}
A Generator is a function of a Tree, which records every change and writes nothing until the generator returns. Compose the packaged library generator with runGenerator, then adjust what it wrote with updateJson:
import type { Generator } from '@hyperfrontend/workspace'
import { runGenerator, updateJson } from '@hyperfrontend/workspace/generators'
interface ServiceOptions {
name: string
}
const service: Generator<ServiceOptions> = async (tree, options) => {
await runGenerator(tree, 'library', {
name: options.name,
directory: 'services',
})
updateJson<{ tags?: string[] }>(tree, `services/${options.name}/project.json`, (project) => ({
...project,
tags: [...(project.tags ?? []), 'type:service'],
}))
tree.write(`services/${options.name}/src/index.ts`, `export const name = '${options.name}'\n`)
}
export default service
A bare name such as library resolves the way the command line resolves it: a workspace project that lists it first, then the packaged generator.
6. Run it
Preview first; nothing is written:
npx hf generate service billing --dry-run
CREATE services/billing/package.json
CREATE services/billing/project.json
CREATE services/billing/src/index.ts
...
UPDATE tsconfig.base.json
hf generate: dry run, nothing written
Then for real:
npx hf generate service billing
Check it worked
npx hf run format:size prints the file's size and exits 0, and npx hf generate service billing leaves services/billing/project.json tagged type:service, ready for npx hf run billing:typecheck.
Reference and background
Next steps
Set up a monorepo and test only what changed
A repository of several TypeScript libraries runs every test on every change, because nothing knows which libraries a change actually reaches.
How to release libraries from their commits
Versions and changelogs written by hand drift from what the commits changed, and nothing stops a push whose versions are wrong.