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 quick start
Quick start
hygen is a project-local code generator: it turns files in a _templates folder into
generated output (new files, injections into existing files, shell commands). This page
covers installing the CLI, bootstrapping a project and generating your first output; the
full template reference is in templates.
Installing the CLI
The fork is published on npm as @biorate/hygen. Install it globally, or run it without
installing:
npm i -g @biorate/hygen
# or, without installing
npx @biorate/hygen ...
The binary is named hygen. When installed globally it is on your PATH; when run via
npx you use the full package name.
Running a generator
A generator is invoked with a GENERATOR ACTION pair. The folder in _templates maps to
the command: _templates/mailer/new/ is the mailer new generator.
hygen mailer new [NAME]
| ^ action
`------- generator
A name is passed positionally as the NAME argument (optionally a comma list — see
Multiple actions and names in one run):
hygen mailer new autumn-newsletter
The --name flag is removed in this fork; use the positional argument (see
Differences from upstream).
Bootstrapping your project
hygen init self copies two starter generators (generator new and
generator with-prompt) into a project-local _templates folder:
cd your-project
hygen init self
# added: _templates/generator/with-prompt/hello.ejs.t
# added: _templates/generator/with-prompt/prompt.js
# added: _templates/generator/new/hello.ejs.t
With the starter generators in place, create and use your own:
hygen generator new mygen
# added: _templates/mygen/new/hello.ejs.t
hygen mygen new
# added: app/hello.js
The starter generator new template is itself copied into your project (not bundled), so
you can tweak how new generators are created for your team. Because templates are
generated by hygen, they are checked in and reviewed like any other code.
Testing a run dry
--dry renders and validates every action but saves nothing (and runs no shell command).
Use it to preview what a generator will do before committing it:
hygen mailer new test --dry
# [no files written, no shell commands run]
Checking the version
--version (or -v) prints Hygen v<version> and exits 0 without needing a generator
or action:
hygen --version
Hygen v0.0.1
hygen -v
Hygen v0.0.1
Getting help
With no arguments, or with an unknown generator/action, the CLI prints the available actions and exits non-zero:
hygen
# Hygen v0.0.1
# Available actions:
# generator: new, with-prompt
# mailer: new
-h / --help prints the usage text:
hygen -h
# Usage:
# hygen [option] GENERATOR ACTION[,ACTION...] [NAME[,NAME...]] [data-options]
#
# Options:
# -h, --help # Show this message and quit
# --dry # Perform a dry run. Files will be generated but not saved.
Templates location
Templates are found by walking up the directory tree from the current working directory
for a _templates folder. The HYGEN_TMPLS environment variable overrides local lookup
(see templates location); in the embeddable API the
location is set via the RunnerConfig (see extensibility).
That's the 30-second tour. Continue with the full reference in templates and generators.
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.