@hyperfrontend/workspace/generators

generators

What the packaged generators are built from, so a generator of your own composes them on the same tree: the tree's JSON, project and template helpers, the names and paths a generator writes, the manifest and alias updates a rename needs, and the running of a generator by name.

GeneratorWhat it writes
workspaceThe root configuration the engine reads, into a repository that has none
libraryA TypeScript library with its project, manifest, configurations and a first spec
make-publishableThe targets, manifest fields, README and e2e project a published package needs
renameA project's new name, carried into everything that refers to it
moveA project under another directory, with its names, aliases and references brought along

A local generator composes them by name through runGenerator, which resolves the name the way the command line does and runs the generator on the tree it is given:

import type { Generator } from '@hyperfrontend/workspace'
import { runGenerator, updateJson } from '@hyperfrontend/workspace/generators'

interface Options {
  name: string
}

const service: Generator<Options> = async (tree, options) => {
  await runGenerator(tree, 'library', {
    name: options.name,
    directory: 'services',
    tags: ['type:service'],
  })
  updateJson<{ tags?: string[] }>(tree, `services/${options.name}/project.json`, (project) => ({
    ...project,
    tags: [...(project.tags ?? []), 'scope:internal'],
  }))
}

export default service

API Reference§

ƒ Functions

§function

addTsConfigPath(tree: Tree, options: AddPathOptions): void

Add a new path mapping to tsconfig.base.json. Maintains alphabetical sorting.
Parameters
NameTypeDescription
§tree
TreeThe virtual file system tree
§options
AddPathOptionsOptions containing package name and project root
Example

Registering a new library's alias

import { addTsConfigPath } from '@hyperfrontend/workspace/generators'

addTsConfigPath(tree, { packageName: '@acme/data-utils', projectRoot: 'libs/utils/data' })
// tsconfig.base.json compilerOptions.paths gains '@acme/data-utils': ['libs/utils/data/src/index.ts'], keys sorted
§function

blockBounds(lines: unknown, opens: (line: string) => boolean, closes: (line: string) => boolean, what: string): BlockBounds

Locate a block by the line that opens it and the first later line that closes it.
Parameters
NameTypeDescription
§lines
unknownThe lines to search
§opens
(line: string) => booleanRecognises the opening line
§closes
(line: string) => booleanRecognises the closing line
§what
stringNames the block in the error raised when it is not there
Returns
BlockBounds
The indices of the opening and closing lines
Example

Locating the rules block of a lint configuration

const lines = ['export default [', '  {', '    rules: {', "      'a': 'error',", '    },', '  },', ']']
blockBounds(lines, (line) => line.trim() === 'rules: {', (line) => line.trim() === '},', 'the rules block')
// => { open: 2, close: 4 }
blockBounds(lines, (line) => line.trim() === 'ignores: [', (line) => line.trim() === '],', 'the ignores block')
// throws: the ignores block: the block that opens it was not found
§function

compactVersion(version: string): string

A version without the trailing zero segments a reader does not need.
Parameters
NameTypeDescription
§version
stringA version such as 22.18.0
Returns
string
The version with trailing .0 segments dropped, 22.18
Example

Dropping the trailing zero segments

compactVersion('18.0.0') // '18'
compactVersion('20.10.5') // '20.10.5'
§function

compileIgnoreRules(text: string, base: string): IgnoreRule[]

The rules of one .gitignore.
Parameters
NameTypeDescription
§text
stringThe file's text
§base
stringThe directory the file sits in, relative to the root, or an empty string
Returns
IgnoreRule[]
The rules in order; comments and blank lines dropped
Example

How the lines of a `.gitignore` are read

compileIgnoreRules('# build output\ndist/\n!dist/keep.txt\n', '')
// => [
//   { negated: false, directoryOnly: true, anchored: false, glob: 'dist', base: '' },
//   { negated: true, directoryOnly: false, anchored: true, glob: 'dist/keep.txt', base: '' },
// ]
§function

findLine(lines: unknown, matches: (line: string) => boolean, from: number): number

Find the first line a predicate accepts.
Parameters
NameTypeDescription
§lines
unknownThe lines to search
§matches
(line: string) => booleanThe predicate
§from
numberThe index to start searching at
Returns
number
The index of the first matching line, or -1 when none matches
Example

The search starts where told

const lines = ['import a from "a"', '', 'export default [', '  a,', ']']
findLine(lines, (line) => line.startsWith('export default'), 0) // => 2
findLine(lines, (line) => line === ']', 3) // => 4
findLine(lines, (line) => line.startsWith('import'), 1) // => -1
§function

formatFiles(tree: Tree, prettier: Prettier): Promise<void>

Formats every created or updated file of the tree in place.
Parameters
NameTypeDescription
§tree
TreeThe tree whose changes are formatted
§prettier
PrettierThe prettier to format with; the workspace's own when omitted(default: ...)
Returns
Promise<void>
Resolves when every file is written back
Example

The last step of a generator

import type { Generator } from '@hyperfrontend/workspace/generators'
import { formatFiles, writeJson } from '@hyperfrontend/workspace/generators'

const addConfig: Generator<{ project: string; skipFormat?: boolean }> = async (tree, options) => {
  writeJson(tree, `libs/${options.project}/custom.json`, { enabled: true })
  if (!options.skipFormat) await formatFiles(tree)
}
§function

generateFiles(tree: Tree, source: string, target: string, substitutions: Substitutions, options: GenerateFilesOptions): void

Writes every file of a template directory under a target directory of the tree.
Parameters
NameTypeDescription
§tree
TreeThe tree written to
§source
stringThe template directory, absolute
§target
stringThe directory the files land under, relative to the tree's root
§substitutions
SubstitutionsThe values the templates name
§options
GenerateFilesOptionsWhether files already there are kept(default: {})
Example

A generator's `files` directory written under the project

import { join } from 'node:path'
import { generateFiles, names } from '@hyperfrontend/workspace/generators'

// files/src/index.ts.template holds: export const <%= names.propertyName %> = '<%= names.name %>'
generateFiles(tree, join(import.meta.dirname, 'files'), 'libs/data-utils', { names: names('data-utils') }, { keepExisting: true })
// writes libs/data-utils/src/index.ts holding "export const dataUtils = 'data-utils'", unless the file is already there
§function

getPackageNameFromProject(tree: Tree, projectRoot: string): string

Get package name from a project's package.json file.
Parameters
NameTypeDescription
§tree
TreeThe virtual file system tree
§projectRoot
stringThe project root path
Returns
string
The package name or null if not found
Example

Telling a package from a bare project

getPackageNameFromProject(tree, 'libs/core') // => '@acme/core'
getPackageNameFromProject(tree, 'apps/docs') // => null
§function

getProjects(tree: Tree): Map<string, ProjectConfiguration>

Every project of the tree, by name.
Parameters
NameTypeDescription
§tree
TreeThe tree read
Returns
Map<string, ProjectConfiguration>
The projects, in path order
Example

A project the same run created is already there

import { getProjects, writeJson } from '@hyperfrontend/workspace/generators'

writeJson(tree, 'libs/data/project.json', { projectType: 'library' })
getProjects(tree).get('data') // => { name: 'data', root: 'libs/data', projectType: 'library' }, named after its directory
§function

globalNameOf(packageName: string): string

The global a browser bundle of a package registers under: the scope and the name as one class name, @scope/my-lib giving ScopeMyLib.
Parameters
NameTypeDescription
§packageName
stringA package name, scoped or not
Returns
string
The identifier a browser attaches the bundle under
Example

The scope becomes part of the global

globalNameOf('@acme/data-utils') // => 'AcmeDataUtils'
globalNameOf('data-utils') // => 'DataUtils'
§function

indentOf(line: string): string

The leading whitespace of a line.
Parameters
NameTypeDescription
§line
stringOne line of the file
Returns
string
Its indentation, empty for a line that starts at the margin
Example

Matching the indentation of a neighbouring line

indentOf('    rules: {') // => '    '
indentOf('\tcommand: "hf-lint .",') // => '\t'
indentOf('export default [') // => ''
§function

isIgnored(path: string, isDirectory: boolean, rules: unknown): boolean

Whether git would ignore a path under the rules in force.
Parameters
NameTypeDescription
§path
stringThe path relative to the root
§isDirectory
booleanWhether the path names a directory
§rules
unknownThe rules in order, the deepest .gitignore last
Returns
boolean
True when the last matching rule ignores it
Example

The last matching rule decides

const rules = compileIgnoreRules('dist/\n!dist/keep.txt\n', '')
isIgnored('libs/core/dist', true, rules) // => true
isIgnored('dist/keep.txt', false, rules) // => false
isIgnored('dist', false, rules) // => false: the rule names directories alone
§function

joinLines(text: TextLines): string

Join lines back into a text with the ending they were split from.
Parameters
NameTypeDescription
§text
TextLinesThe lines and their ending
Returns
string
The text
Example

Editing a line and writing the file back byte for byte

const text = splitLines(tree.read('lint.base.config.ts', 'utf-8') ?? '')
text.lines.splice(3, 0, "  '@acme/lint-rules',")
tree.write('lint.base.config.ts', joinLines(text)) // the file keeps its CRLF or LF endings
§function

joinPathFragments(...fragments: unknown): string

Fragments joined and normalised as a POSIX path; a native path among them is made portable first.
Parameters
NameTypeDescription
§...fragments
unknownThe parts of the path
Returns
string
The joined path with forward slashes
Example

A path fit for a configuration file, whatever the platform

joinPathFragments('libs', 'utils\\data', './package.json') // => 'libs/utils/data/package.json'
§function

moveTsConfigPaths(tree: Tree, options: MovePathOptions): void

Update path mappings for a moved project in tsconfig.base.json. Updates both the key (package name) and value (file path). Maintains alphabetical sorting.
Parameters
NameTypeDescription
§tree
TreeThe virtual file system tree
§options
MovePathOptionsOptions with current/new roots and package names
Example

Moving the aliases with the directory, keeping the name

moveTsConfigPaths(tree, {
  currentProjectRoot: 'libs/core',
  newProjectRoot: 'packages/core',
  currentPackageName: '@acme/core',
  newPackageName: '@acme/core',
  updateName: false,
})
// '@acme/core': ['libs/core/src/index.ts'] became '@acme/core': ['packages/core/src/index.ts']
§function

names(name: string): Names

The forms of a name.
Parameters
NameTypeDescription
§name
stringAny spelling, such as my-lib, myLib or MY_LIB
Returns
Names
The class, property, constant and file forms
Example

The forms a template reads

names('data-utils')
// => { name: 'data-utils', className: 'DataUtils', propertyName: 'dataUtils', constantName: 'DATA_UTILS', fileName: 'data-utils' }
names('DataUtils').fileName // => 'data-utils'
§function

nodeFloorOf(range: string): string

The lowest version an engines range names: the first version number in it.
Parameters
NameTypeDescription
§range
stringAn engines range such as >=22.18.0
Returns
string
The version, 22.18.0
Example

Reading the floor of an engines range

nodeFloorOf('>=18.0.0') // '18.0.0'
nodeFloorOf('^20.10 || >=22') // '20.10'
§function

offsetFromRoot(directory: string): string

The relative path from a directory back to the root it is under: one ../ per segment.
Parameters
NameTypeDescription
§directory
stringA directory relative to the root, such as libs/utils/data
Returns
string
./ for the root itself, else ../ repeated once per segment
Example

Pointing a project's tsconfig at the base one

`${offsetFromRoot('libs/utils/data')}tsconfig.base.json` // => '../../../tsconfig.base.json'
offsetFromRoot('.') // => './'
§function

prettierOf(root: string): Prettier

The prettier a workspace installs, resolved from its root the way any module of the workspace resolves it.
Parameters
NameTypeDescription
§root
stringThe workspace root, absolute
Returns
Prettier
Its API
Example

Formatting a text with the workspace's prettier and configuration

const prettier = prettierOf(tree.root)
const options = { ...(await prettier.resolveConfig(`${tree.root}/libs/core/src/index.ts`, { editorconfig: true })), filepath: 'index.ts' }
await prettier.format('export const a={b:1}', options) // => "export const a = { b: 1 }\n"
§function

quote(value: string): string

Write a value as a single-quoted TypeScript string literal.
Parameters
NameTypeDescription
§value
stringThe text
Returns
string
The literal, with backslashes and quotes escaped
Example

Writing a path into TypeScript source

quote('@acme/core') // => "'@acme/core'"
quote("it's") // => "'it\\'s'"
quote('C:\\repo') // => "'C:\\\\repo'"
§function

readJson<Value>(tree: Tree, path: string): Value

The value of a JSON file of the tree.
Parameters
NameTypeDescription
§tree
TreeThe tree the file is read from
§path
stringThe file, relative to the root
Returns
Value
The parsed value
Example

Reading a manifest the tree holds

import { readJson } from '@hyperfrontend/workspace/generators'

readJson<{ name: string; version: string }>(tree, 'libs/core/package.json') // => { name: '@acme/core', version: '1.0.0' }
readJson(tree, 'libs/core/missing.json') // throws: Cannot find libs/core/missing.json
§function

readPackageJsonInfo(tree: Tree, projectRoot: string): PackageJsonInfo

Read package name, description and keywords from a project's package.json.
Parameters
NameTypeDescription
§tree
TreeThe virtual file system tree
§projectRoot
stringThe project root path
Returns
PackageJsonInfo
Package name and description
Example

A project with and without a manifest

readPackageJsonInfo(tree, 'libs/core') // => { name: '@acme/core', description: 'Core library.', keywords: ['core', 'acme'] }
readPackageJsonInfo(tree, 'apps/docs') // => { name: null, description: '', keywords: [] } when apps/docs has no package.json
§function

readProjectConfiguration(tree: Tree, name: string): ProjectConfiguration

One project of the tree.
Parameters
NameTypeDescription
§tree
TreeThe tree the project is read from
§name
stringWhich project
Returns
ProjectConfiguration
Its configuration
Example

The root a generator writes under

const project = readProjectConfiguration(tree, 'lib-core')
// => { name: 'lib-core', root: 'libs/core', projectType: 'library', targets: { build: { ... } } }
tree.write(`${project.root}/src/generated.ts`, 'export const generated = true\n')
§function

readRootManifest(tree: Tree): RootManifest

The root package.json of the tree, or nothing when the tree has none.
Parameters
NameTypeDescription
§tree
TreeThe tree whose root is looked at
Returns
RootManifest
The manifest's fields the generators inherit from
Example

What a new package inherits

import { readRootManifest, scopeOf } from '@hyperfrontend/workspace/generators'

const root = readRootManifest(tree)
// => { name: '@acme/workspace', license: 'MIT', repository: { type: 'git', url: 'https://github.com/acme/workspace.git' } }
scopeOf(root.name ?? '') // => '@acme'
§function

renameTsConfigPaths(tree: Tree, options: RenamePathOptions): void

Rename path mappings in tsconfig.base.json. Handles both exact matches and prefixed paths (e.g., @pkg/sub). Maintains alphabetical sorting.
Parameters
NameTypeDescription
§tree
TreeThe virtual file system tree
§options
RenamePathOptionsOptions with current and new package names
Example

The entry points of a package are renamed with it

renameTsConfigPaths(tree, { currentPackageName: '@acme/core', newPackageName: '@acme/kernel' })
// '@acme/core' and '@acme/core/testing' became '@acme/kernel' and '@acme/kernel/testing'; '@acme/core-ui' is untouched
§function

renderExpression(expression: string, substitutions: Substitutions): string

The text an expression renders as: the value a dotted path names, optionally with one .replace("search", "replacement") applied; a missing member renders as nothing.
Parameters
NameTypeDescription
§expression
stringThe text between <%= and %>
§substitutions
SubstitutionsThe values
Returns
string
The text
Example

Dotted paths and the one call a template may make

const substitutions = { names: names('data-utils'), packageName: '@acme/data-utils' }
renderExpression('names.className', substitutions) // => 'DataUtils'
renderExpression('packageName.replace("@", "")', substitutions) // => 'acme/data-utils'
renderExpression('names.missing', substitutions) // => ''
renderExpression('other', substitutions) // throws: other is not defined for the template
§function

renderTemplate(template: string, substitutions: Substitutions): string

A template with every <%= expression %> rendered.
Parameters
NameTypeDescription
§template
stringThe template text
§substitutions
SubstitutionsThe values
Returns
string
The rendered text
Example

Rendering one template text

renderTemplate('export class <%= names.className %> {}\n', { names: names('data-utils') })
// => 'export class DataUtils {}\n'
§function

replaceDescriptionPackageName(json: JsonWithDescription, currentPackageName: string, newPackageName: string): void

Update description field by replacing package name references. Mutates the json object in place for use inside updateJson callbacks.
Parameters
NameTypeDescription
§json
JsonWithDescriptionThe JSON object to update
§currentPackageName
stringPackage name to replace
§newPackageName
stringReplacement package name
Example

Inside an `updateJson` updater

import type { NamedJson } from '@hyperfrontend/workspace/generators'
import { replaceDescriptionPackageName, updateJson } from '@hyperfrontend/workspace/generators'

updateJson<NamedJson>(tree, 'e2e/core/project.json', (json) => {
  replaceDescriptionPackageName(json, '@acme/core', '@acme/kernel')
  return json // description "E2E tests for @acme/core" now reads "E2E tests for @acme/kernel"
})
§function

runGenerator(tree: Tree, written: string, options: Record<string, unknown>, importModule: ImportModule): Promise<void>

Runs the generator a name means over a tree, so a generator composes another by name: a workspace's own generator of that name, else the engine's.
Parameters
NameTypeDescription
§tree
TreeThe tree the generator edits, rooted at the workspace
§written
stringThe generator as the command line names it, <name> or <package>:<name>
§options
Record<string, unknown>The options the generator is called with
§importModule
ImportModuleImports a module from its absolute path; the process's own import when omitted(default: ...)
Returns
Promise<void>
Resolves when the generator has run
Example

A workspace generator composing the packaged `library` generator

import type { Generator } from '@hyperfrontend/workspace/generators'
import { runGenerator } from '@hyperfrontend/workspace/generators'

const featureLibrary: Generator<{ name: string }> = async (tree, options) => {
  await runGenerator(tree, 'library', { name: options.name, tags: ['type:feature'], skipFormat: true })
  tree.write(`libs/${options.name}/src/feature.ts`, 'export const feature = true\n')
}
export default featureLibrary
§function

scopedName(scope: string, name: string): string

The package name a scope and a name make.
Parameters
NameTypeDescription
§scope
stringThe scope with its @, or undefined for no scope
§name
stringThe name under the scope
Returns
string
@scope/name, or the name alone
Example

Renaming a package under its current scope

scopedName(scopeOf('@acme/core'), 'kernel') // => '@acme/kernel'
scopedName(undefined, 'kernel') // => 'kernel'
§function

scopeOf(packageName: string): string

The scope of a package name.
Parameters
NameTypeDescription
§packageName
stringA package name, scoped or not
Returns
string
The scope with its @, or undefined for an unscoped name
Example

Scoped and unscoped names

scopeOf('@acme/core') // => '@acme'
scopeOf('lodash') // => undefined
§function

sortPaths(paths: Record<string, string[]>): Record<string, string[]>

Sort paths object alphabetically by key.
Parameters
NameTypeDescription
§paths
Record<string, string[]>The paths object to sort
Returns
Record<string, string[]>
Sorted paths object
Example

A stable order for the alias map

sortPaths({ '@acme/utils': ['libs/utils/src/index.ts'], '@acme/core': ['libs/core/src/index.ts'] })
// => { '@acme/core': ['libs/core/src/index.ts'], '@acme/utils': ['libs/utils/src/index.ts'] }
§function

splitLines(content: string): TextLines

Split a text into lines, keeping the line ending it uses.
Parameters
NameTypeDescription
§content
stringThe text to split
Returns
TextLines
The lines and their ending
Example

The ending is remembered, not normalised

splitLines('a\r\nb\r\n') // => { lines: ['a', 'b', ''], eol: '\r\n' }
splitLines('a\nb') // => { lines: ['a', 'b'], eol: '\n' }
§function

unscopedName(packageName: string): string

A package name without its scope.
Parameters
NameTypeDescription
§packageName
stringA package name, scoped or not
Returns
string
The part after the scope's slash, or the name as given
Example

The name a directory takes

unscopedName('@acme/core') // => 'core'
unscopedName('lodash') // => 'lodash'
§function

updateContentReferences(tree: Tree, options: UpdateContentOptions): void

Update all content references (README + JSDoc). Convenience function combining updateReadmeReferences and updateModuleJSDoc.
Parameters
NameTypeDescription
§tree
TreeThe virtual file system tree
§options
UpdateContentOptionsOptions containing project root and package names
Example

Carrying a package's new name into its prose

import { updateContentReferences } from '@hyperfrontend/workspace/generators'

updateContentReferences(tree, { projectRoot: 'libs/core', currentPackageName: '@acme/core', newPackageName: '@acme/kernel' })
// libs/core/README.md and the @module header of libs/core/src/index.ts now say @acme/kernel
§function

updateJson<Value>(tree: Tree, path: string, updater: (value: Value) => Value): void

Rewrites a JSON file through an updater.
Parameters
NameTypeDescription
§tree
TreeThe tree the file lives in
§path
stringThe file, relative to the root
§updater
(value: Value) => ValueMaps the current value to the one written
Example

Adding a target to an existing project

import type { ProjectConfiguration } from '@hyperfrontend/workspace/generators'
import { updateJson } from '@hyperfrontend/workspace/generators'

updateJson<ProjectConfiguration>(tree, 'libs/core/project.json', (json) => {
  json.targets = { ...json.targets, docs: { command: 'typedoc' } }
  return json
})
§function

updateModuleJSDoc(tree: Tree, options: UpdateContentOptions): void

Update @module JSDoc tags in source files.
Parameters
NameTypeDescription
§tree
TreeThe virtual file system tree
§options
UpdateContentOptionsOptions containing project root and package names
Example

Only the entry's `@module` tag is rewritten

updateModuleJSDoc(tree, { projectRoot: 'libs/core', currentPackageName: '@acme/core', newPackageName: '@acme/kernel' })
// "@module @acme/core" in libs/core/src/index.ts now reads "@module @acme/kernel"; other mentions of the name stay
§function

updateProjectReferences(tree: Tree, options: UpdateReferencesOptions): void

Renames a project in every other project's implicitDependencies and dependsOn entries.
Parameters
NameTypeDescription
§tree
TreeThe tree the configurations live in
§options
UpdateReferencesOptionsThe current and new names, and the roots to skip
Example

The projects that depend on a renamed one follow it

updateProjectReferences(tree, { currentProjectName: 'lib-core', newProjectName: 'lib-kernel' })
// e2e/core/project.json: implicitDependencies ['lib-core'] became ['lib-kernel']
// apps/shell/project.json: a target's dependsOn ['lib-core'] became ['lib-kernel']; '^build' entries are untouched
§function

updateReadmeReferences(tree: Tree, options: UpdateContentOptions): void

Update README.md with new package name references.
Parameters
NameTypeDescription
§tree
TreeThe virtual file system tree
§options
UpdateContentOptionsOptions containing project root and package names
Example

Every mention in the README follows the package

updateReadmeReferences(tree, { projectRoot: 'libs/core', currentPackageName: '@acme/core', newPackageName: '@acme/kernel' })
// "npm install @acme/core" in libs/core/README.md now reads "npm install @acme/kernel"; a project without a README is left alone
§function

visitNotIgnoredFiles(tree: Tree, directory: string, visitor: (path: string) => void): void

Visits every file under a directory of the tree that git would not ignore.
Parameters
NameTypeDescription
§tree
TreeThe tree walked
§directory
stringWhere to start, relative to the root; an empty string or . for the root
§visitor
(path: string) => voidCalled with each file's path relative to the root
Example

Rewriting every source file of a project

import { visitNotIgnoredFiles } from '@hyperfrontend/workspace/generators'

visitNotIgnoredFiles(tree, 'libs/core', (path) => {
  if (!path.endsWith('.ts')) return
  const content = tree.read(path, 'utf-8') ?? ''
  tree.write(path, content.replaceAll('@acme/core', '@acme/kernel'))
})
// libs/core/node_modules and anything libs/core/.gitignore lists are never visited
§function

writeJson(tree: Tree, path: string, value: unknown): void

Writes a value as two-space JSON with a trailing newline.
Parameters
NameTypeDescription
§tree
TreeThe tree the file is written to
§path
stringThe file, relative to the root
§value
unknownWhat to write
Example

A new project's manifest

writeJson(tree, 'libs/core/project.json', { name: 'lib-core', projectType: 'library', targets: { build: {} } })
tree.read('libs/core/project.json', 'utf-8') // => '{\n  "name": "lib-core",\n  "projectType": "library",\n  "targets": {\n    "build": {}\n  }\n}\n'

◈ Interfaces

§interface

AddPathOptions

Options for adding a new path mapping.
Properties
§packageName:stringnpm package name (e.g., '@hyperfrontend/data-utils')
§projectRoot:stringProject root path (e.g., 'libs/utils/data')
§interface

BlockBounds

The first and last line of a bracketed block.
Properties
§open:numberIndex of the line that opens the block
§close:numberIndex of the line that closes the block
§interface

Funding

Where sponsorship of a package goes.
Properties
§type?:stringThe platform
§url?:stringThe page
§interface

IgnoreRule

One line of a .gitignore, read.
Properties
§readonly negated:booleanWhether a match re-includes the path.
§readonly directoryOnly:booleanWhether the rule matches directories alone.
§readonly anchored:booleanWhether the pattern names a path under the ignore file's directory rather than a name at any depth.
§readonly glob:stringThe glob, without its anchors.
§readonly base:stringThe directory the ignore file sits in, relative to the root, or an empty string.
§interface

JsonWithDescription

JSON object with an optional description field.
Properties
§description?:unknownOptional description text
§interface

MovePathOptions

Options for moving path mappings.
Properties
§currentProjectRoot:stringCurrent project root path
§newProjectRoot:stringNew project root path
§currentPackageName:stringCurrent npm package name
§newPackageName:stringNew npm package name
§updateName:booleanWhether the name is being updated
§interface

NamedJson

A project or package manifest as far as a rename reads it.
Properties
§description?:unknownOptional description text
§name?:stringThe project or package name
§interface

Names

The forms of a name.
Properties
§readonly name:stringThe name as given.
§readonly className:stringUpperCamelCase.
§readonly propertyName:stringlowerCamelCase.
§readonly constantName:stringCONSTANT_CASE.
§readonly fileName:stringlower-hyphenated.
§interface

PackageJsonInfo

Result of reading package.json metadata.
Properties
§name:stringPackage name or null if not found
§description:stringPackage description or empty string
§keywords:string[]npm keywords, empty when the package declares none
§interface

Prettier

The part of prettier's API that formatting the tree uses.
Methods
§format(source: string, options: Record<string, unknown>): Promise<string>
Formats a text with options.

Parameters

NameTypeDescription
§source
string
§options
Record<string, unknown>
§getFileInfo(file: string, options: FileInfoOptions): Promise<FileSupport>
Whether a file is ignored and which parser handles it.

Parameters

NameTypeDescription
§file
string
§options
FileInfoOptions
§resolveConfig(file: string, options: ResolveConfigOptions): Promise<Record<string, unknown>>
The configuration that applies to a file, or null when none does.

Parameters

NameTypeDescription
§file
string
§options
ResolveConfigOptions
§interface

ProjectConfiguration

The parts of a project.json a generator reads, with the project's name and root settled.
Properties
§name:stringThe project's name: the file's, or its directory's.
§root:stringThe project's directory, relative to the root.
§sourceRoot?:stringWhere its sources live.
§description?:stringWhat the project is for.
§projectType?:stringThe kind of project.
§tags?:string[]The tags the module boundaries read.
§implicitDependencies?:string[]Projects depended on without an import.
§targets?:Record<string, unknown>The targets, by name.
§metadata?:Record<string, unknown>Free-form metadata.
§interface

RenamePathOptions

Options for renaming path mappings.
Properties
§currentPackageName:stringCurrent npm package name
§newPackageName:stringNew npm package name
§interface

Repository

Where a repository's packages are kept, as the root manifest states it.
Properties
§type?:stringThe kind of repository, such as git
§url?:stringIts URL
§directory?:stringThe directory of one package within it
§interface

RootManifest

The root package.json as far as the generators read it: what every package of the workspace inherits from it.
Properties
§name?:stringThe workspace's own name, whose scope its packages take
§license?:stringThe licence its packages are under
§repository?:string | RepositoryThe repository its packages are kept in
§funding?:string | FundingWhere sponsorship goes
§engines?:Record<string, string>The engines its packages run on
§interface

TextLines

A text split into lines, remembering the line ending it was written with so it can be joined back without changing a single byte it did not mean to.
Properties
§lines:string[]The lines, without their endings
§eol:stringThe ending every line was separated by
§interface

Tree

A virtual file tree: reads fall through to the files, writes are recorded until committed.
Properties
§readonly root:stringThe directory every path is relative to, absolute.
Methods
§children(path: string): string[]
The names directly under a directory.

Parameters

NameTypeDescription
§path
string
§delete(path: string): void
Records a file's deletion.

Parameters

NameTypeDescription
§path
string
§exists(path: string): boolean
Whether a file or directory is there.

Parameters

NameTypeDescription
§path
string
§isFile(path: string): boolean
Whether the path names a file.

Parameters

NameTypeDescription
§path
string
§listChanges(): TreeChange[]
Every change recorded so far.
§read(path: string): Buffer<ArrayBufferLike>
The content of a file, or null when there is none.

Parameters

NameTypeDescription
§path
string
read(path: string, encoding: "utf-8"): string
The text of a file, or null when there is none.

Parameters

NameTypeDescription
§path
string
§encoding
"utf-8"
§write(path: string, content: string | Buffer<ArrayBufferLike>): void
Records a file's content.

Parameters

NameTypeDescription
§path
string
§content
string | Buffer<ArrayBufferLike>
§interface

TreeChange

One change a tree has recorded since it was opened.
Properties
§readonly path:stringThe path, relative to the tree's root, POSIX.
§readonly type:"CREATE" | "UPDATE" | "DELETE"What happened to the file.
§readonly content?:Buffer<ArrayBufferLike>The content written, or nothing for a deletion.
§interface

UpdateContentOptions

Options for updating content references.
Properties
§projectRoot:stringProject root path
§currentPackageName:stringCurrent npm package name
§newPackageName:stringNew npm package name
§interface

UpdateReferencesOptions

How a project is renamed in the configurations that refer to it.
Properties
§currentProjectName:stringThe project's current name
§newProjectName:stringThe project's new name
§excludeRoots?:string[]The roots of projects whose configuration is left alone, such as the moved project's old and new roots

◆ Types

§type

Generator

A generator: the default export of the module a generators manifest names.
type Generator = (tree: Tree, options: Options) => unknown
§type

Substitutions

The values a template may name.
type Substitutions = Readonly<Record<string, unknown>>

● Variables

§type

DEFAULT_NODE_ENGINE

The Node.js range a package declares when it declares none of its own.
§type

DEFAULT_NPM_ENGINE

The npm range a package declares when it declares none of its own.
§type

PRINT_WIDTH

The line width the workspace's formatter wraps at. A transform that writes a line longer than this would be rewritten by the next format pass, so the transforms break such a line themselves and running them twice changes nothing.