Part of @biorate/hygen — a fork of jondot/hygen (v6.2.11, MIT), adapted to the
@biorate/*monorepo. Rewritten for this fork's semantics; see Differences from upstream.Based on: Upstream generators guide
Generators
A generator is a folder under _templates. The folder structure maps to the command
structure, so building a new generator is just creating a folder and a template file.
Structure
_templates/
mailer/
new/
html.ejs.t
text.ejs.t
route/
new/
handler.ejs.t
inject_handler.ejs.t
hygen mailer new renders every file in _templates/mailer/new/ (html.ejs.t and
text.ejs.t). hygen walks the template folder recursively, so you can nest generators as
elaborately as you like; the command still applies to the whole action folder.
Each template file begins with a --- frontmatter block (see templates for
the full reference). The .t suffix keeps your editor from treating it as an already
compiled file — hygen does not care about file names or types, only the folder structure
and the contents.
Creating a generator
hygen generator new (from the starter templates copied by hygen init self) scaffolds a
generator for you:
hygen generator new mailer
# added: _templates/mailer/new/hello.ejs.t
The scaffolding template lives in your project (_templates/generator/new/hello.ejs.t), so
you can change how hygen generates generators for your team.
CLI arguments
Any double-dash (--) argument becomes a template variable:
hygen mailer new foobar --message hello --version 1
---
to: app/emails/<%= name %>.html
---
<h1>Hello <%= name %></h1>
<%= message %>
(version <%= version %>)
Interactive picker (no arguments)
Run hygen with no positional arguments in a terminal and a two-level picker lets you
choose a generator, then an action, instead of an error; the run then proceeds
exactly as if you had typed hygen <generator> <action>, with all flags (--keep-going,
data options, …) intact. In a non-interactive environment (CI, piped stdio) the picker
never launches and the run fails fast with the usual missing-arguments error, so scripted
exit codes are preserved.
See Interactive picker for the full reference — the two-level flow,
the TTY fallback and the interactive option.
Interactive prompts
Add a prompt.js to the action folder to collect values interactively before rendering
(the complete reference — file names, hook forms, filtering, TypeScript — lives in
prompts):
_templates/
mailer/
new/ <- the mailer new generator
prompt.js <- your prompt file!
html.ejs.t
text.ejs.t
For example, to ask for message:
module.exports = [
{
type: 'input',
name: 'message',
message: "What's your message?",
},
];
The prompt format is enquirer. The answers become template variables:
---
to: app/emails/<%= name %>.txt
---
<%= message %>
The name variable still comes from the CLI:
hygen mailer new fancy-mailer
Templates within an action folder are applied in localeCompare order.
Advanced prompts (index.js)
Replace prompt.js with an index.js in the action folder to build a multi-step flow, skip
prompting conditionally, or reshape CLI arguments in a central place (the complete hook
reference — lookup order, hook arguments, filtering — lives in prompts):
my-generator/
my-action/
index.js
template1.ejs.t
template2.ejs.t
Instead of exporting an array, export an object with a prompt function (and an optional
params function):
// my-generator/my-action/index.js
module.exports = {
prompt: ({ prompter, args }) =>
prompter
.prompt({
type: 'input',
name: 'email',
message: "What's your email?",
})
.then(({ email }) =>
prompter.prompt({
type: 'input',
name: 'emailConfirmation',
message: `Please type your email [${email}] again:`,
}),
),
};
The prompt function receives a structure with a prompter field. params reshapes CLI
arguments into new variables:
// my-generator/my-action/index.js
module.exports = {
params: ({ args }) => {
return { moreConvenientName: args.foobamboozle };
},
};
Documenting generators
The message frontmatter prop builds generator help screens. A help action with a blank
template and a message: renders as the help text:
---
message: |
- hygen {bold mailer} new [NAME]
---
The | annotation is a YAML literal block. message: supports chalk-style coloring:
{bold mailer}
{red mailer}
{underline mailer}
{green mailer}
Selecting parts of a generator
hygen GENERATOR ACTION:SUBACTION selects a subset of a generator's files, where
SUBACTION is a string or regular expression matched against the file name:
hygen mailer new:text textual-mailer
# renders only text.ejs.t
hygen mailer new:.*xt textual-mailer
# same, via regular expression
Multiple actions and names in one run
Both the action and the name positionals accept a comma-separated list, so one command can render several actions and/or several names:
# two actions, one name
hygen mailer new,html my-mailer
# one action, two names (name-outer: each name completes all its actions)
hygen mailer new a,b
# two actions AND two names
hygen mailer model,controller a,b
Action lists
hygen mailer new,html fancy-mailer
The listed actions run sequentially in list order — new completes fully before
html starts. Each listed action runs its own prompt hook and its own render pipeline;
shared values come from CLI flags (see prompts). A
ACTION:SUBACTION selector applies within each listed action, so you can restrict every
action in the list the same way (hygen mailer new:text,html:text x).
Name lists
hygen mailer new a,b
A name list multiplies with a batch action too: a template declaring
glob: is expanded once per name.
This renders new once per name. The loop is name-outer: each entity completes all
its actions before the next entity starts. For model,controller × a,b the execution
order is (model,a), (controller,a), (model,b), (controller,b). Inside templates,
name is always a scalar — the current expansion's value — never an array.
The bare variant works too: when the action folder does not exist, the second positional
is treated as the (comma-list) name for the generator's _default action:
hygen crud a,b — or, combined with an action list, hygen crud new,html a,b.
Fail fast vs --keep-going
Failure policy is fail-fast by default: the first failing pair stops the run and the
error names the specific action (and name) that failed. Set --keep-going to continue
through the remaining pairs and collect every failure:
hygen mailer new,html a,b --keep-going
With --keep-going, the returned RunnerResult carries both the partial actions that
did complete and a failures list — one entry per failed pair (action, optional name,
error). Fail-fast pairs raise the error immediately (in the embeddable runner() API,
result.failure.message names the pairing that went wrong, and any prior actions are
already on disk).
No transactionality — use --dry first
A multi-run is sugar over sequential runs, not a transaction: there is no rollback.
If an early pair succeeds and a later one fails, the earlier output stays on disk. On
fail-fast runs this leaves partial results. To preview what a multi-run would write, run
with --dry (hygen mailer new,html a,b --dry) — files are generated but not saved —
before committing to a real run.
Templates location
hygen finds _templates by walking up the directory tree from the working directory and
using the first one it finds. The HYGEN_TMPLS environment variable overrides local lookup
(and takes priority over it), which is useful for scripting or pointing at a shared template
root:
HYGEN_TMPLS=/path/to/other/templates hygen mailer new x
In the embeddable API, the location is set via RunnerConfig.templates (and
templatesOverride); see extensibility.
That's it for generators. Next: the FAQ and extensibility.
Attribution
@biorate/hygen is a fork of jondot/hygen (v6.2.11,
MIT); original work © Dotan Nahum, fork adaptations © Leonid Levkin. See
Differences from upstream and the LICENSE.