How-to › Model, configure and generate

How to migrate a Yeoman generator without losing its composition#

Port a Yeoman generator's composed sub-generators to components that one command still runs in order, and hold the port to the original's output with a test.

Audience
Library maintainer
Level
advanced
Topic
Generate code and projects
Languages
TypeScript
Verified

Your Yeoman generator asks three questions and composes three sub-generators, and its ci step reads the package.json that an earlier step wrote in the same run. Port it to a tool without composition and the one command becomes three. Run the ci command first and it writes a workflow with no test step, because the file it reads does not exist yet.

What you get

You will end up with the generator ported to jostraca components that one command runs in order, and a test that holds the port to Yeoman’s output byte for byte. This is for you if you maintain a Yeoman generator built on composeWith.

Short answer

Port each Yeoman sub-generator to a jostraca cmp() component that reads the prompt answers as its model, and call the components inside one Project, so one command still runs them all. Move into the model any value that one sub-generator read from a file an earlier one wrote. Keep the prompts in your own code, since jostraca has none, and test the port with mem: true against a yeoman-test run of the original.

You will need

Node 22.22.2 or later, the Yeoman generator you are moving, and its yeoman-test suite. Verified 2026-11-22 against jostraca 0.42.0, yeoman-generator 10.3.1, yeoman-environment 8.9.0, yeoman-test 11.8.2, orval 8.48.0 and OpenAPI Generator 7.27.0. The sample generator, service, has an app generator that prompts and then composes package, src and ci.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
CopierThe template has to update the projects it already madePython and Git, plus one answers file and one update command per templateYour steps share answers or output within one run
jostracaSub-generators become components in one tree, tested in memoryNo prompts and no install step, so both move into code you writeYour users expect a prompt-driven tool and nobody will write code
OpenAPI Generator files nodeThe sub-generators only add a few files beside a generated clientLogic-less Mustache templates, a Java runtime, and answers passed as additionalPropertiesThe scaffold holds logic, or files unrelated to the client
orval generate()A TypeScript client is one step of the scaffold, run by the same commandIt writes API code only, so every other file in the scaffold needs another toolYour clients are not TypeScript
PlopA flat set of prompts and actions inside a repository that already existsOne generator per command; chaining means a custom action calling getGenerator(name).runActionsYour sub-generators depend on each other’s answers or output
YeomanThe generator works, and composition is the part you would loseA run loop, mem-fs, and EJS templates that somebody has to keep currentNobody on the team will maintain the generator’s dependencies

Voxgig maintains jostraca, the only one of these six it makes, and the table does not rank it.

Plop is the smallest port, and each sub-generator becomes a command of its own unless a custom action calls the next one through getGenerator. Copier replays a later tag of the template over a project it made, from the answers it recorded there, at the price of a separate answers file and update per template. jostraca keeps composition as plain function calls and leaves the questions to you.

Map each Yeoman concept before you port

Write the map first. Every row is a decision, and the second and fourth are where ports go wrong.

Yeomanjostraca port
prompting() and this.promptYour own code: flags, then node:readline questions, then defaults (port/answers.mjs)
composeWith(path, options)A component call inside one Project; the options become the model
this.fs.copyTpl with EJSContent with $$path$$ substitution; EJS loops and conditions become JavaScript
Reading another sub-generator’s output from mem-fsNot possible while the tree is defined, so the value moves into the model
The install that yeoman-environment queues when package.json changesNothing; the port’s user runs npm install
yeoman-test with withAnswersJostraca({ mem: true }), res.vol().toJSON(), and a file-by-file comparison you write (runs.mjs)

The fourth row matters because jostraca writes nothing until the tree is complete. Yeoman runs composed generators priority by priority, in the order composeWith was called, so a later writing() can read an earlier one’s file.1 A component cannot.

Port a sub-generator to a component

The ci sub-generator read scripts back out of package.json. In the port, the model holds the scripts, and both the package component and the workflow component read them from there.

// Was the ci sub-generator. It reads the scripts from the model, not from a
// package.json that another component may or may not have written yet.
export const Workflow = cmp(function Workflow(props) {
  const steps = Object.keys(props.ctx$.model.scripts).filter((s) => s === 'test' || s === 'lint')
  Folder({ name: '.github' }, () => {
    Folder({ name: 'workflows' }, () => {
      File({ name: 'ci.yml' }, () => {
        Content(`name: $$service$$ ci
on: [push]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
`)
        for (const s of steps) Content(`      - run: npm run ${s}\n`)
      })
    })
  })
})

The EJS loop became a for. $$service$$ is replaced with the model value as text, with no escaping, so the answers are checked before the tree is built.

export function toModel(answers) {
  const a = { ...DEFAULTS, ...answers }
  if (typeof a.name !== 'string' || !NAME.test(a.name)) {
    throw new Error(`service name ${JSON.stringify(a.name)} is not a lowercase package name`)
  }
  if (!Number.isInteger(a.port) || a.port < 1 || a.port > 65535) {
    throw new Error(`port ${JSON.stringify(a.port)} is not an integer from 1 to 65535`)
  }

Compose the components in one command

composeWith becomes three calls in one Project. The order no longer matters, because no component reads a file that a sibling wrote.

  return jostraca.generate({ folder }, () => {
    Project({}, () => {
      PackageJson()
      Server()
      if (model.ci) Workflow()
    })
  })
}

port/bin.mjs is the command that replaces yo service. It asks only when a person is at the terminal, and --dry-run sets jostraca’s control.dryrun, which lists the files and writes none.

node port/bin.mjs --name orders --port 8080 --out orders --dry-run
would write package.json
would write src/server.js
would write .github/workflows/ci.yml

Check it worked

Run the original and the port on the same answers and compare every file. runs.mjs runs Yeoman through yeoman-test2 and the port in memory, and leaves out jostraca’s own .jostraca/ folder.

node compare.mjs
answers {"name":"orders","port":8080,"ci":true}
  .github/workflows/ci.yml   identical, 160 bytes
  package.json               identical, 124 bytes
  src/server.js              identical, 220 bytes
answers {"name":"billing","port":9090,"ci":false}
  package.json               identical, 125 bytes
  src/server.js              identical, 221 bytes
every file identical

The tests hold it there. They compare three answer sets and show that a changed port number is caught. They refuse names such as o'reilly and ../x, and check that a memory run and a dry run leave the disk untouched. Two more pin the pitfalls below.

node --test parity.test.mjs records.test.mjs
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0

When it goes wrong

The workflow loses its test step. The sub-generators were ported one for one into separate commands, and ci ran before package, so the file it reads was not there.

node pitfall.mjs
yo service (composed)          npm ci, npm run test
yo service:package, then :ci   npm ci, npm run test
yo service:ci first            npm ci
port, Workflow called first    npm ci, npm run test

Both ported orders give the full workflow, because the port reads the scripts from the model. Find every this.fs.read and readJSON in your sub-generators before you port, and move each value it reads into the model.

A service name with a quote in it breaks server.js differently in each tool. The EJS tag <%= escapes HTML, so the original wrote o&#39;reilly, and $$service$$ writes the quote itself, which ends the JavaScript string early. Validate answers in toModel, as the sample does, so a bad name fails before a file exists.

A port test passes on an empty run. Assert that the Yeoman run wrote files before comparing, as parity.test.mjs does, or two empty trees compare equal.

Run the client step with orval or OpenAPI Generator

orval writes API code and nothing else, so it has no mechanism for the rest of a scaffold. A team that generates its client with orval keeps the client step in the scaffold’s command through orval’s programmatic API. with-orval.mjs runs the port and then generate(), and generate.sh ran it once and committed what it wrote.

const res = await generateService({ name: 'orders', port: 8080, ci: true }, { folder: out })
for (const f of res.files.written) console.log(`jostraca wrote ${f.slice(out.length + 1)}`)

// generate() logs a failed generation and resolves unless throwOnError is set.
await generate({
  input: { target: resolve('api.json') },
  output: { target: join(out, 'src/client/bookshelf.ts'), client: 'fetch' },
}, process.cwd(), { throwOnError: true })
if (!existsSync(join(out, 'src/client/bookshelf.ts'))) throw new Error('orval wrote no client')
console.log('orval wrote src/client/bookshelf.ts')

A team on OpenAPI Generator can move a sub-generator that only adds files into the generator’s own configuration. Its files node renders a template as a supporting file, and additionalProperties carries the answers.

generatorName: typescript-fetch
inputSpec: api.json
templateDir: openapi-generator/templates
additionalProperties:
  service: orders
files:
  ci.yml.mustache:
    templateType: SupportingFiles
    folder: .github/workflows
    destinationFilename: ci.yml

show-records.mjs reads both runs back from the committed files.

node show-records.mjs
node with-orval.mjs, one command, wrote:
  package.json
  src/server.js
  .github/workflows/ci.yml
  src/client/bookshelf.ts
orval client functions: createBook, deleteBook, getBook, listBooks, updateBook
OpenAPI Generator wrote 12 files, its FILES list names 10, among them .github/workflows/ci.yml
its ci.yml is byte-identical to the port's: true

The Mustache template writes the test step as fixed text, since a logic-less template cannot filter the scripts. OpenAPI Generator’s batch command runs several configurations in one command, and its !include property lets them share one file of settings.

When not to do this

Do not port a generator that works and has someone keeping its dependencies current. Yeoman’s composition is the feature this page spends most of its length rebuilding.

Do not choose jostraca if your users expect to answer questions and get a project. It has no prompt layer and no install step, so the port carries port/answers.mjs and whatever runs npm install afterwards.

Do not port to Plop or Copier and then document the order of the commands. If sub-generators share answers or files, keep them in one run.

If the scaffold exists mainly to wrap a client, OpenAPI Generator’s files node may be the whole generator you need. It suits a team whose extra files are few, static and tied to the client, which is less to maintain than a component tree. Keep orval for the client alone: its generate() call fits inside whatever command writes the rest. Copier suits a fleet of projects that must take template updates.

Last verified

Verified 2026-11-22 against Node 22.23.5, jostraca 0.42.0, shape 12.2.5, yeoman-generator 10.3.1, yeoman-environment 8.9.0, yeoman-test 11.8.2, orval 8.48.0 and OpenAPI Generator 7.27.0. Every output block is what the command preceding it printed. orval and OpenAPI Generator ran once in generate.sh, and the page’s commands read what they committed. Plop and Copier were not run; their rows come from their documentation, read on the same day.

Footnotes

  1. Yeoman’s page on composing generators introduces the idea by comparison with Voltron, trademark sign included. It names two ways to start a composition, by a generator or by the end user, and then adds that the second is a planned feature and not available. ↩︎ Back to text

  2. The test suite this port replaces has its own drift. Yeoman’s testing page shows answers passed with withPrompts. yeoman-test 11.8.2 still accepts the call and marks it deprecated in its type declarations. Its compiled source hands the answers on to withAnswers in one line. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.