Generating with conformetry

Conformetry generators render a template — an ordinary folder of ordinary files — into an instance on disk. The same template is then the standard the instance is measured against, so generating is not a convenience. Code written by hand in a shape a template already describes starts life failing conformance.

Before you write a file by hand, check for a generator

A generator name you guess at is rejected, so read the registry rather than inferring it:

conformetry templates --config configuration/conformetry.config.ts

Every conformetry command requires --config <path>; no default file is assumed. In an Nx workspace, the emitted plugin answers the same question:

nx list conformetry

Both read the live configuration, so they are correct for the workspace you are in. Neither output is worth caching in a note — it changes as generators are added.

Generation overwrites, unconditionally

There is no existence check, no skip-if-exists, no merge, and no conflict detection anywhere in the write path. Every file in the template is rendered and written over whatever is there.

Never point a generator at a path that already holds work you want. To change an existing instance, edit it. Regenerate only when you intend to discard what is there, or when the instance is missing files a template requires and you have read what will be replaced.

The Nx path writes through a Tree, so --dry-run is honest and shows exactly what would land:

nx g conformetry:<generator> --name=<name> --project=<project> --dry-run

Do that first when you are unsure where output will go.

The two entrypoints disagree about inputs

This is the single most confusing thing about generating, and it is not a bug: the same generator behaves differently depending on how you invoke it.

The remaining asymmetry is about when a missing value is caught. The Nx path requires every declared input up front, so it refuses before rendering starts. The command-line host requires none of them, and catches the omission at the moment a template asks for it — MissingSubstitutionError, naming the placeholder and the template file.

So an input a template never interpolates can be omitted on the command-line host and not on the Nx path. Anything a template does interpolate is required on both.

Pass every input explicitly on either path. A template that means "optional" says so with a section — {{#owner}}…{{/owner}} renders nothing when owner is absent — rather than relying on a bare {{owner}}.

A generator is addressed by its full name on both paths — there are no short alternative names. Both hosts list the real names when you get one wrong.

The flag is --template, not --generator. It matches the word the configuration (templatePath), the templates command, and the conformance report already use. --generator was removed rather than kept as an alias, and passing it is refused by name — this command accepts unknown flags so a template's inputs can be passed as flags, so without that refusal a stale script would have its --generator silently dropped and appear to work.

--template is also optional at the command line. Omitting it at a terminal offers an autocomplete over every configured template, each with its description; an agent shell is not a terminal, so always pass it — omitted there, the run is refused with the available names listed rather than left waiting on a prompt.

Where the output lands

On the Nx path the destination is resolved in this order, first match winning:

1. An explicit --directory.
2. No project input — treated as a new project, placed by its type input alongside projects of the same type.
3. A module input — placed in that existing module. Naming a module that does not exist is an error, not an invitation to create one.
4. The generator's own scoped directory, from the first tagged pattern in its instance groups.
5. The directory already holding the most instances of that generator.
6. The project root.

Steps 4 and 5 are why a generator usually needs no destination at all: it knows where its own instances live. Reach for --directory when you are deliberately placing something outside that convention.

On the command-line host only --directory applies, and its absence means generated/<generator-name> — a scratch location, not your source tree. Always pass --directory there when you mean to write into the workspace.

Running without a person present

The command-line host prompts whenever stdin is a terminal, and there is no flag to turn that off — an attached terminal is the whole condition, so an agent shell, a hook, or a CI job is never prompted.

Every input a generator declares is required, on both entrypoints: a generator substitutes each of its placeholders, and mustache renders a missing one as an empty string rather than failing, so an optional input would quietly put a hole in the generated file. With no terminal, an input you did not pass is therefore a hard error naming the flag to pass — never a silent default, and never a menu drawn where nothing can answer it. Pass every input the template declares, or run where you can be asked.

After generating

Two steps, both cheap, both catching a whole class of mistake:

1. Check conformance of what you just made. A generated instance conforms by construction, so a difference means the destination was wrong, an input was empty, or you overwrote something. See the conformetry-validate skill.
2. Implement inside the generated files. Do not build a parallel structure beside them. The template's section comments and declarations are the contract; adding to them is always allowed, removing them is what breaks.

When a generator does not exist yet

Adding one is a configuration change, not a code change — see the conformetry-configure skill. Two things bite immediately after: the emitted Nx plugin has to be regenerated with nx sync, and every conformetry command refuses to run while it is out of date rather than working from stale definitions.

Seeing it rather than reading about it

conformetry-examples is twelve self-contained examples, each with its own configuration, template, instances, and command. Two are worth running before scaffolding something unfamiliar:

• hello-template — the smallest generator that exists, generated and then validated in two commands, so the loop is visible end to end.
• case-variants — every derived case variant in paths and in contents, and how an explicit input overrides one.

Each runs in about a second and its guide quotes the output it produces, which the package's own test suite asserts. See its AGENTS.md for which example answers which question.