Each team that starts a service copies the last one and edits it, so the Dockerfile still exposes
the previous service’s port and the CI workflow pins a Node version nobody chose. Your scaffolder fixes the copy
step, but its only test runs it into a temporary folder, and a second run over an edited project
overwrites the README the team wrote.
What you get
You will end up with a jostraca generator that turns four answers into a runnable service skeleton, with a test that builds the whole tree in memory. This is for you if your platform team recreates one service layout by hand.
Short answer
Write the generator as a jostraca define function: check the answers, then declare Project,
Folder, File, Content and Copy, and read nothing from disk. Let generate write the tree,
or build it in memory with mem: true for a unit test. Leave each decision about a file that
already exists to the build phase, such as exclude on a README. A define phase that reads the
output folder sees the real disk in a memory run.
You will need
Node.js 20 or later, and a service layout you already recreate by hand. The sample pins
jostraca 0.42.0 with its peer shape 12.2.5, and yaml 2.9.1 for the test that reads the
workflow. Its answers are in answers.json: a name, a one-line description, a port, and a Node
major version.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Cookiecutter | Anyone should read the template by opening a folder of files named with variables | Logic lives in hooks and template expressions, and a unit test runs the whole render | The layout varies by answer more than by value |
| jostraca | The generator is a program you refactor, and you test its tree in memory | A reader follows code to see the layout, and there is no prompt or CLI | A folder anyone can read at a glance matters more |
| OpenAPI Generator | The service starts from an OpenAPI document and a server stub generator | A Java runtime or Docker, a stub with eleven caret-ranged dependencies, and Mustache for extra files | You have no document yet, or want your own server layout |
| Plop | Small additions inside an existing repository, from prompts | A flat list of add, modify and append actions per generator, over Handlebars templates | The output is a whole project with structure |
| Speakeasy | You need the SDK, CLI or MCP server for a service that already has a document | No service target, and an account for generation | The task is the service itself |
| Yeoman | Generators with prompts, composed from other generators and published to npm | Imperative this.fs.copyTpl calls spread over run-loop methods, with EJS templates | You want the tree as one declaration you can test |
Voxgig maintains jostraca, the worked path on this page, in a GitHub organization of its own
named jostraca. The other five rows are tools Voxgig does not make.
The trade-off is a program against a folder. Cookiecutter’s template is the layout, so anyone can read it, a change to the layout is a change to files, and logic goes in hooks. jostraca’s layout is code, so it can be refactored and tested in memory, and reading it takes a programmer. Yeoman and Plop sit between them, with code that writes each file from a template in a call or an action of its own.
Declare the tree and nothing else
service checks the answers, then returns the define function. It declares every file and reads
nothing, so one function serves a disk run, a memory run, and a dry run.
export function service(answers, { template = TEMPLATE } = {}) {
const a = checkAnswers(answers)
return () => {
// A $$name$$ in Project's folder is not substituted, so the name is an expression.
Project({ folder: a.name }, () => {
File({ name: 'package.json' }, () => Content(packageJson(a)))
File({ name: 'Dockerfile' }, () => Content(dockerfile(a)))
// Once the README exists it is the team's. exclude skips a file only when it is already
// there, and jostraca decides that when it writes, not here.
File({ name: 'README.md', exclude: true }, () => Content(readme(a)))
Folder({ name: 'src' }, () => {
File({ name: 'server.mjs' }, () => Content(server(a)))
})
Folder({ name: '.github' }, () => {
Folder({ name: 'workflows' }, () => {
File({ name: 'ci.yml' }, () => Content(workflow(a)))
})
})
Copy({ from: template })
})
}
}
checkAnswers refuses a name outside lowercase letters, digits and hyphens, and a port outside
1024 to 65535. It also refuses a Node major other than 20, 22 or 24, and a description with a
quote, a backtick, a dollar sign, or a line break. Content runs jostraca’s $$path$$
substitution over the text it is given, which escapes nothing, so the check keeps an answer from
carrying a $$path$$ of its own. package.json is built with JSON.stringify, and the name
reaches server.mjs the same way.
TEMPLATE is an absolute path built from import.meta.url. Copy resolves a relative from
against the working directory, where Fragment resolves it against the output folder, as the
copy how-to
says. A test runs both from another directory.
Write the tree and run what it wrote
scaffold.mjs is the build phase. It passes a pinned clock and a quiet logger, because jostraca’s
default logger writes to standard output, and a Copy of one binary file sends it a DEBUG block.
/** The build phase: walk the declared tree and write it, to disk or to memory. */
export async function scaffold(answers, folder, { mem = false, vol, now = () => 0 } = {}) {
const jostraca = Jostraca({ now, log: quiet, ...(mem ? { mem: true, vol: vol ?? {} } : {}) })
return jostraca.generate({ folder }, service(answers))
}
demo.mjs scaffolds into a scratch folder, runs the generated project’s own test, starts its
server, then edits the README and scaffolds again over the same folder.1
node demo.mjs
tide-service/ holds 7 files
.dockerignore
.github/workflows/ci.yml
Dockerfile
README.md
package.json
src/server.mjs
test/health.test.mjs
node --test in tide-service: pass 1, fail 0
GET /health -> 200 {"status":"ok","service":"tide-service"}
second run wrote 0 files; README.md kept the edit: yes
The service has no dependencies, so the workflow runs npm test after actions/setup-node with
the answer’s Node version, and needs no install step. The Dockerfile is checked as text by the
tests and never built here. jostraca writes its .jostraca/ record beside tide-service/, in the
output folder, so the project itself carries none of it.
Keep the define phase off the disk
The pitfall takes one existsSync call. pitfall.mjs writes the README rule twice: once as
a check on the output folder inside the define function, and once as exclude. Each runs on disk
and in memory, over a project whose README the team has edited.
node pitfall.mjs
define phase reads the disk edited README on disk: kept in memory: lost
build phase decides (exclude) edited README on disk: kept in memory: kept
Both versions pass on disk, which is why the first survives review. In memory, existsSync asks
the real disk about /out, finds nothing, and declares a README that overwrites the edited one
in the volume. exclude is read in FileOp.after, which asks the run’s own filesystem whether
the file exists, at
line 80 of FileOp.ts.
The in-memory how-to
seeds a volume with vol in the same way.
Check it worked
Thirteen tests cover the tree in memory, the answers in each file, the generated test, and the server started by its own command. Others check two byte-identical runs, the README rule, the refused answers, the pitfall, and the record.
node --test scaffold.test.mjs
1..13
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
Look for # pass 13. The first test builds the tree in memory and asserts that the working
directory is still empty afterwards. The fourth runs node src/server.mjs, the command the
Dockerfile and npm start name, and gets 200 from /health.
When it goes wrong
The project lands in a folder called $$name$$. Project({ folder }) takes its value as written,
and a test shows the substitution working in Content and not in the folder. Pass the name as a
JavaScript expression.
The edited README is overwritten although the File carries existing: { txt: { write: false } }.
In 0.42.0 that option is read from Jostraca() or generate() only, and a File reads only
the name, exclude and mode its components reference lists. A test shows a File holding
existing overwritten without a message. Use exclude: true on the file, or a global
existing.
The memory test throws ENOENT on the template. Copy reads its source through the run’s
filesystem, so a memory run needs the template files seeded in vol, as the test’s seed does.
Scaffold the same service with OpenAPI Generator or Speakeasy
OpenAPI Generator starts from a document. Its nodejs-express-server generator writes an Express
stub, and a configuration file’s files node adds your own Mustache templates as supporting
files, rendered with additionalProperties. record.sh ran it on oag/health.json, with the
answers in oag/config.yaml:
head -8 records/openapi-generator.txt
openapi-generator 7.27.0
nodejs-express-server on health.json: 16 files
Dockerfile: no, .github/workflows: no
with -c config.yaml: 18 files
added: .github/workflows/ci.yml Dockerfile
listed in .openapi-generator/FILES: 2 of 2
Dockerfile rendered from templates/Dockerfile.mustache:
FROM node:22-alpine
The stub’s package.json lists eleven dependencies, each by a caret range, which the record
names. It was not installed or started here.
Speakeasy’s quickstart has no target for a service. Its
quickstart reference lists
cli, csharp, go, java, mcp-typescript, php, postman, python, ruby, terraform
and typescript. A team on Speakeasy scaffolds the service with a generator such as this one
and publishes its OpenAPI document. Speakeasy then reads that document for the SDK, once its
CLI is authenticated
with a Speakeasy account.
When not to do this
Do not write a jostraca generator for a layout that varies only by value. Cookiecutter’s folder of templated names does that job, and a reader sees the result without running anything.
Do not let the define phase look at the output folder. Every decision about an existing file belongs to the build phase, or the memory test stops describing a real run.
Pick OpenAPI Generator when the service is defined by its document first, since the stub is generated from the operations the document already declares. Speakeasy suits the next step, once the service publishes a document and needs SDKs in several languages. Yeoman fits a generator that prompts and composes other published generators, which jostraca, with no CLI of its own, leaves to you.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, jostraca 0.42.0, shape 12.2.5 and yaml 2.9.1, which
the captured commands run. record.sh ran OpenAPI Generator 7.27.0 on Java 21 once. Cookiecutter,
Plop, Yeoman and Speakeasy were not run; their rows come from their own documentation, read on the
same day, and Speakeasy needs an account to generate anything.
Footnotes
-
jostraca’s tutorial opens by saying a generator earns its keep on the second run, the one that arrives after somebody has edited the output. Its last step regenerates a config file a user has changed. The scaffold on this page meets that second run on its README. ↩︎ Back to text