How-to › Model, configure and generate

How to scaffold a service with a component-based generator#

Turn four answers into a runnable Node service with its Docker and CI files, using the jostraca component tree, and test the tree in memory before writing a file.

Audience
Platform team
Level
beginner
Topic
Generate code and projects
Languages
TypeScript
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
CookiecutterAnyone should read the template by opening a folder of files named with variablesLogic lives in hooks and template expressions, and a unit test runs the whole renderThe layout varies by answer more than by value
jostracaThe generator is a program you refactor, and you test its tree in memoryA reader follows code to see the layout, and there is no prompt or CLIA folder anyone can read at a glance matters more
OpenAPI GeneratorThe service starts from an OpenAPI document and a server stub generatorA Java runtime or Docker, a stub with eleven caret-ranged dependencies, and Mustache for extra filesYou have no document yet, or want your own server layout
PlopSmall additions inside an existing repository, from promptsA flat list of add, modify and append actions per generator, over Handlebars templatesThe output is a whole project with structure
SpeakeasyYou need the SDK, CLI or MCP server for a service that already has a documentNo service target, and an account for generationThe task is the service itself
YeomanGenerators with prompts, composed from other generators and published to npmImperative this.fs.copyTpl calls spread over run-loop methods, with EJS templatesYou 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.

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

  1. 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

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.