yeoman-generator: the library behind Yeoman project scaffolding

What yeoman-generator actually provides

The repository is not the Yeoman command line tool. It is the library underneath it, published to npm under the name yeoman-generator, and its own description repeats the project tagline: a Rails-inspired generator system that provides scaffolding for your apps.

The scope of the library is generator authoring. The README states that a generator can be as complex as you want it to be, ranging from a program that copies a bunch of boilerplate files to one that asks the user for preferences and scaffolds a tailored project. The decision about which one to write is left to the author. That is the whole design brief: the library provides the machinery, the generator author decides the output.

Two entry points are documented. The getting started guide at yeoman.io/authoring covers the basics, and the API documentation at yeoman.io/generator lists the available methods. The README also points to the source code itself for anyone who wants to go further.

The fastest route for a new author is not to write from scratch. The README points to generator-generator, a Yeoman generator whose job is to generate a Yeoman generator, hosted at github.com/yeoman/generator-generator. Using it means you get the package layout, the entry point and the test wiring in the shape the ecosystem expects, and you concentrate on the part that is actually your project.

The ESM package shape and what it means for consumers

The package.json is short enough to read in full and it makes several decisions that affect you directly. The published artifact is built to dist. The type field is module, so the package is ESM only, and the exports map exposes two conditions.

"exports": {
  ".": {
    "types": "./dist/index.d.js",
    "default": "./dist/index.js"
  },
  "./typed": {
    "types": "./dist/index.d.js",
    "import": "./dist/index.js"
  }
}

Both conditions resolve to the same file, so the./typed subpath is a compatibility alias rather than a separate build. There is no require condition, which means a CommonJS consumer cannot load this package through require. For a tool that templates Node projects this is mostly a non-issue, since most modern Node tooling is ESM, but it will stop a project that still runs on CommonJS.

The files field lists only dist, so only the compiled output ships. The types entry points are named with a.d.js suffix, which is unusual, and the build script has a matching step that copies declaration files by hand, because the pattern that TypeScript's declaration emit produces does not align with the export map without help.

"build": "tsc && npm run copy-types",
"copy-types": "cpy --cwd=src \"**/*.d.(|c|m)ts\" ../dist/"

For anyone extending the library, that copy-types step is the one to know about. A hand written declaration file in src is only present in the published package because of it.

The pretest gate that decides whether a change ships

The most instructive part of package.json is the pretest script, because it shows what the maintainers consider the definition of a correct change. Nothing runs until four checks pass in sequence.

"pretest": "eslint . && prettier . --check && npm run build && tsc -p tsconfig.spec.json",
"test": "vitest run --coverage"

Lint first, then formatting, then the build, then a separate typecheck of the spec files under tsconfig.spec.json. The test run itself is vitest with coverage, and coverage is reported to coveralls through c8. The unit tests live in test/ and the runner is configured in vitest.config.ts, with .mocharc.cjs also present in the repository root, a leftover from an earlier Mocha based setup.

Two style tools coexist here. Prettier handles formatting and eslint handles linting, with eslint.config.js at the root, and there is also an .xo-config.json file, the XO opinionated preset that the project appears to have moved away from. The fix script runs both in write mode, and prepare runs the build, so an install from a git checkout compiles the package automatically.

The practical takeaway for a contributor is that the local test command is slow in a good way. Any change touches lint, format, compile and typecheck before a single assertion runs, and the build step inside pretest means you cannot pass the suite with a package that does not compile.

Building the docs and how releases are cut

Documentation is generated with JSDoc rather than a TypeDoc setup, and the doc script is a three step chain. It generates the JSDoc output into a sibling directory named yeoman-generator-doc, strips the HTML comment wrappers that the generator leaves behind, and then formats the result with Prettier using a separate ignore file for documentation paths.

"doc": "npm run doc:generate && npm run doc:fix && npm run doc:prettier",
"doc:generate": "jsdoc -c jsdoc.json -d $npm_package_config_doc_path$DOC_FOLDER",
"doc:prettier": "prettier $npm_package_config_doc_path$DOC_FOLDER --write --ignore-path .prettierignore-doc"

The doc_path config points at../yeoman-generator-doc, a directory outside the package. That layout is unusual but it keeps the generated site out of the published tarball and lets the docs live in their own repository.

Releases are cut by release-please, and the presence of.release-please-manifest.json and release-please-config.json alongside CHANGELOG.md says the changelog is generated from commit messages rather than written by hand. The version history in the repository shows the pattern: v9.2.0 on 2026-09-14, then v10.0.0 and v10.0.1 both on 2026-10-07, a major and its patch landing the same day. The 10.0.0 release is the one to pay attention to, since a major bump in a library consumed by many published generators is where breaking changes live, and CHANGELOG.md is where the project records them.

Where yeoman-generator is the wrong tool

The first limitation is the ESM only packaging. A generator that is itself a CommonJS package, or a project on an older Node setup, cannot require this library. The workaround is to write the generator as ESM, which is fine in 2026 and was not fine five years ago.

The second limitation is the documentation drift. The README links API documentation for v4.x at yeoman.github.io/generator/4.x while the package is on version 10.0.1. The current site at yeoman.io/generator is the one to trust, but the fact that a 4.x link is still in the README is a fair signal about how carefully the docs are refreshed. Anyone porting a generator from an older Yeoman release should expect to read the source rather than the guide.

The third limitation is the weight of the toolchain. eslint, prettier, a tsc build, a declaration copy step, vitest with coverage, jsdoc and c8 is a lot of machinery for a library whose job is to template files. A team that only needs a directory scaffold with a couple of prompts has several simpler options.

The fourth limitation is the composition model itself. Yeoman generators compose by running other generators and by writing files through the environment, and the ordering of those steps is where the classic Yeoman bugs live, the duplicated file, the prompt asked twice, the dependency installed twice. The library gives you the tools to avoid that, but it does not prevent it, and there is no high level guardrail.

yeoman-generator next to plop, hygen and cookiecutter

The comparison that matters is with template driven scaffolders, because they solve the same problem from a different direction.

plop takes handlebars templates and a config file, and generators are declared as prompts plus a list of template files. It has no programmatic lifecycle, so a generator cannot compute an answer, run a shell command during generation, or decide dynamically which templates to emit. What you get in exchange is far less code and a config file that non-programmers can read.

hygen takes the same idea further with the template file carrying its own front matter, so a template describes when it applies and what it needs. The generator is a matching operation rather than a program. It suits projects that want repeatable, reviewable changes to an existing codebase.

cookiecutter is the same shape in Python, with a cookiecutter.json of variables and a template directory, and it remains the reference point for the project-generation question across languages.

yeoman-generator sits at the opposite end. It is a library you write code against, with a full object model for the environment, the destination directory, prompts and installed dependencies. When the output depends on what is already in the target directory, or on the answers, or on running a command to inspect the machine, that is where a programmatic generator wins and a template matcher stops being enough. The cost is that you own the code, the tests and the ordering, and you inherit the classic Yeoman failure modes that come with that ownership.

Licence, sponsorship and the state of the project

yeoman-generator is BSD 2-Clause, and the LICENSE file in the repository root carries the BSD text with a copyright line naming Google. The original author of the project is recorded as Yeoman in package.json. A two clause BSD is a permissive licence that allows use inside commercial products, including proprietary tools, and its only real obligation is to keep the copyright and licence notice in redistributions. Anyone with a specific commercial arrangement should read the LICENSE file itself rather than take that as advice.

The project is not archived and the last push was on 2026-10-15, so the code is being worked on. The release history confirms a recent cadence, with a major and a patch release in the same week in October 2026 and a minor in September. The repository also carries integration and coverage badges in the README, a coverage report pushed to coveralls and a GitHub Actions integration workflow, which together indicate that the test suite runs against real environments rather than only in unit tests.

Funding runs through OpenCollective, and the README asks for sponsorship to cover project expenses, with a long list of individual backers. That is a signal about the project's economics rather than its code: the library is free to use and the maintenance is funded by donations and by the organisations that depend on the Yeoman ecosystem.

Editorial conclusion

Adopt yeoman-generator if you are writing a generator that belongs in the Yeoman ecosystem or need its prompt and composition model, and if your project already runs on ESM. Skip it if you need CommonJS compatibility, or if a template-driven tool such as plop fits your scaffolding better without a programming model. Before starting a generator, run npm test in a clone and read the version 10 migration notes in CHANGELOG.md, because the API documentation linked from the README still describes the 4.x line.

Frequently asked questions

Official sources

1. License: BSD-2-Clause
2. Project website
3. README
4. Releases
5. yeoman/generator on GitHub