TutorialVerified · workspace 0.0.0· 2026-11-07beginner~20 min

Set up a monorepo and test only what changed

You will start from an empty directory, create three TypeScript libraries that depend on one another, and watch hf affected run the tests a change reaches and skip the one it does not, with the reason for each.

Everything comes from @hyperfrontend/workspace.

Create the repository

mkdir acme && cd acme
git init
npm init -y
npm pkg set name=@acme/monorepo
npm install --save-dev @hyperfrontend/workspace @hyperfrontend/testing \
  @hyperfrontend/linter prettier @types/node

The root package's scope becomes the scope of every library you generate, so @acme/monorepo gives you @acme/... packages. @hyperfrontend/testing runs the specs.

Make it a workspace

npx hf generate workspace
CREATE .gitignore
CREATE .hfignore
CREATE hf.json
CREATE lint.base.config.ts
CREATE tsconfig.base.json

hf.json is the file every command reads. Open it: its targetDefaults give every project a typecheck, test and build target, each run by an executor of the package such as @hyperfrontend/workspace:test. A project only has to name a target to get it.

Generate three libraries

npx hf generate library format
npx hf generate library report
npx hf generate library cli

Each lands under libs/ with its own project.json, package.json and configuration, and an alias in tsconfig.base.json so the others can import it as @acme/<name>.

Write the code

format formats byte counts. Replace libs/format/src/index.ts:

/** A unit a byte count is shown in. */
export type Unit = 'B' | 'KB' | 'MB' | 'GB'

const UNITS: readonly Unit[] = ['B', 'KB', 'MB', 'GB']

/** Formats a byte count for people to read. */
export function formatBytes(bytes: number): string {
  let value = bytes
  let unit = 0
  while (value >= 1024 && unit < UNITS.length - 1) {
    value /= 1024
    unit += 1
  }
  return `${Math.round(value * 10) / 10} ${UNITS[unit]}`
}

and give it a spec, libs/format/src/index.spec.ts:

import { describe, expect, it } from '@hyperfrontend/testing'
import { formatBytes } from './index'

describe('formatBytes', () => {
  it('rounds to one decimal place', () => {
    expect(formatBytes(1536)).toBe('1.5 KB')
  })
})

report calls formatBytes. Replace libs/report/src/index.ts:

import { formatBytes } from '@acme/format'

/** One line of a size report. */
export function reportLine(file: string, bytes: number): string {
  return `${file}: ${formatBytes(bytes)}`
}

with its spec, libs/report/src/index.spec.ts:

import { describe, expect, it } from '@hyperfrontend/testing'
import { reportLine } from './index'

describe('reportLine', () => {
  it('names the file and its size', () => {
    expect(reportLine('app.js', 2048)).toBe('app.js: 2 KB')
  })
})

cli only needs the Unit type. Replace libs/cli/src/index.ts:

import type { Unit } from '@acme/format'

/** The unit the command line reports in unless told otherwise. */
export const DEFAULT_UNIT: Unit = 'KB'

Run a task, then many

npx hf run format:test

run runs exactly that one task. To build everything, use run-many:

npx hf run-many -t build --all
hf run-many: format:build
hf run-many: cli:build
hf run-many: report:build
3 succeeded, 0 failed, 0 skipped

format builds first. Nothing told it to: the build default in hf.json says "dependsOn": ["^build"], and the workspace knows from the imports that report and cli depend on format.

See what the graph knows

npx hf graph explain report
report (lib, libs/report)
depends on
  → project:format
      value production (1 file): libs/report/src/index.ts

Every dependency is recorded with its kind (value) and the role of the file that made it (production). The same command on cli shows its import of format as type. That distinction is what the next step uses.

Change one library

Commit, so there is something to compare against:

git add -A && git commit -m "feat: three libraries"

Then change how format rounds: in libs/format/src/index.ts, make it two decimal places.

return `${Math.round(value * 100) / 100} ${UNITS[unit]}`

Ask which tests the change affects, and run them:

npx hf affected -t test --base=HEAD
hf affected: 2 tasks selected from 1 changed files
  succeeded format:test
  succeeded report:test

Two of three. Ask why:

npx hf graph affected --target test --base HEAD --explain
test: 2 of 3 tasks selected
  format:test
      changed-input libs/format/src/index.ts: libs/format/src/index.ts is an input of format:test
  report:test
      reachable-from-entry libs/format/src/index.ts: libs/format/src/index.ts reaches report:test
        via file:libs/report/src/index.ts → entry:@acme/format → file:libs/format/src/index.ts
skipped 1 tasks
  cli:test
      kind-irrelevant libs/format/src/index.ts: reachable only through type-only imports, which test does not follow

cli depends on format, yet its test is skipped: it imports format for a type alone, and types are stripped before a test runs, so no change in format can change what cli:test executes. Run the same question for typecheck and cli is selected, because a type check reads types.

You now have a workspace whose tasks run by name, in dependency order, and only where a change reaches. Every decision selectAffected makes names its rule and the file behind it, so when CI skips or runs a task you can read why.

Reference and background

Next steps