@hyperfrontend/workspace/generators/hooks

hooks

Installs the Git hooks a workspace configures into the clone: one POSIX sh stub per hook that has steps in hooks.config.ts, written into the repository's hooks directory and starting hf hooks run <hook>. A workspace without a configuration gets a first one, with a format step before a commit and the affected checks before a push, and .gitignore gains the line that keeps a clone's hooks.local.config.ts out of the repository.

npx hf generate hooks
OptionWhat it sets
--forceReplace a hook file that neither this generator nor Lefthook wrote
--skipFormatLeave the first configuration unformatted

Running it again is how a change to the configured hooks reaches the clone: it rewrites its own stubs, takes the place of Lefthook's, and removes the stubs of hooks that no longer have steps. A repository installs its hooks on every install by naming the generator in the prepare script of its root manifest; where the CI variable is set or there is no repository it writes nothing and succeeds, so the script is harmless in a deploy build.

It writes nothing, and says why, where the workspace is not the root of its repository or Git reads the hooks from a directory outside the workspace. The steps, the skips and the commands are described under /git-hooks.

API Reference§

ƒ Functions

§function

hooksGenerator(tree: Tree, options: HooksGeneratorOptions, env: Readonly<Record<string, string | undefined>>): Promise<void>

Installs the hooks of the workspace into the clone: a POSIX sh stub per configured hook in the repository's hooks directory, each starting hf hooks run <hook>. A workspace without a hooks.config.ts gets a first one. It writes nothing and succeeds where CI is set or there is no repository, so a root prepare script may run it in every install; it says why and writes nothing where the workspace is not the root of its repository or Git reads the hooks from a directory outside it.
Parameters
NameTypeDescription
§tree
TreeThe tree, rooted at the workspace
§options
HooksGeneratorOptionsWhether to replace a foreign hook file, and whether to format(default: {})
§env
Readonly<Record<string, string | undefined>>The environment, this process's unless another is given(default: process.env)
Returns
Promise<void>
Resolves when the stubs are written
Examples

Installing the hooks of a clone

npx hf generate hooks

On every install of the repository, from its root manifest

{ "scripts": { "prepare": "hf generate hooks" } }
§function

stubDirectory(tree: Tree, env: Readonly<Record<string, string | undefined>>): string

The hooks directory the stubs of a tree's workspace go to, saying why when there is one reason worth saying and no directory.
Parameters
NameTypeDescription
§tree
TreeThe tree, rooted at the workspace
§env
Readonly<Record<string, string | undefined>>The environment
Returns
string
The directory, relative to the tree's root, or null when no stub is to be written
Example

Writing stubs only where a clone can take them

import { DEFAULT_HOOKS, stubDirectory, writeStubs } from '@hyperfrontend/workspace/generators/hooks'

const directory = stubDirectory(tree, process.env) // => '.git/hooks' in a clone, null in a deploy build
if (directory !== null) writeStubs(tree, { directory, hooks: DEFAULT_HOOKS, force: false })
§function

writeHooksSetup(tree: Tree): void

Writes what a workspace's hooks start from: the first configuration, unless the workspace has one, and the line that keeps a clone's local file out of the repository.
Parameters
NameTypeDescription
§tree
TreeThe tree, rooted at the workspace
Example

Giving a workspace of your own generator its hooks

import { writeHooksSetup } from '@hyperfrontend/workspace/generators/hooks'

writeHooksSetup(tree) // writes hooks.config.ts when missing, and adds hooks.local.config.ts to .gitignore
§function

writeStubs(tree: Tree, request: StubRequest): void

Writes the stub of every configured hook into a hooks directory, removes this package's and Lefthook's stubs of hooks no longer configured, and leaves every other file alone.
Parameters
NameTypeDescription
§tree
TreeThe tree, rooted at the workspace
§request
StubRequestThe directory, the hooks and whether to replace a foreign file
Example

Installing two hooks into the repository of the tree

import { writeStubs } from '@hyperfrontend/workspace/generators/hooks'

writeStubs(tree, { directory: '.git/hooks', hooks: ['pre-commit', 'pre-push'], force: false })

◈ Interfaces

§interface

HooksGeneratorOptions

What the hooks generator takes.
Properties
§force?:booleanReplace a hook file that neither this generator nor Lefthook wrote
§skipFormat?:booleanSkip formatting the configuration written
§interface

StubRequest

The stubs to install and where.
Properties
§readonly directory:stringThe hooks directory, relative to the tree's root, POSIX.
§readonly hooks:unknownThe hooks that have steps.
§readonly force:booleanWhether a file somebody else wrote is replaced.

● Variables

§type

DEFAULT_HOOKS

The hooks the first configuration gives steps.