Skip to main content

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.