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

Source: https://voxgig.com/howto/scaffold-a-service-with-a-component-generator

- Audience: platform-team
- Level: beginner
- Languages: typescript
- Verified: 2026-11-22
- Published: 2026-11-22

## 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](https://cookiecutter.readthedocs.io/en/stable/tutorials/tutorial2.html) | 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](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/how-to/write-a-file-tree.md) | 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](https://openapi-generator.tech/docs/customization/#user-defined-templates) | 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](https://plopjs.com/documentation/) | 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](https://www.speakeasy.com/docs/speakeasy-reference/cli/quickstart) | 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](https://yeoman.io/authoring/file-system.html) | 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](https://cookiecutter.readthedocs.io/en/stable/advanced/hooks.html). 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.

```js title="generator.mjs"
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](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/how-to/copy-a-directory.md)
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.

```js title="scaffold.mjs"
/** 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]

```bash
node demo.mjs
```

```text output
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.

```bash
node pitfall.mjs
```

```text output
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`](https://github.com/jostraca/jostraca/blob/v0.42.0/ts/src/op/FileOp.ts#L80).
The [in-memory how-to](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/how-to/generate-in-memory.md)
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.

```bash
node --test scaffold.test.mjs
```

```text output
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`:

```bash
head -8 records/openapi-generator.txt
```

```text output
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](https://www.speakeasy.com/docs/speakeasy-reference/cli/quickstart) 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](https://www.speakeasy.com/docs/speakeasy-reference/cli/getting-started)
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

- [Compose one generated file from several components](/howto/compose-generated-files-with-slots-and-fragments)

- [Pick a jostraca file mode for each generated file type](/howto/pick-a-jostraca-file-mode-per-extension)

- [Generate a code section with code instead of a template](/howto/generate-a-code-section-with-a-component)

- [Test a project generator without writing files to disk](/howto/test-a-generator-without-writing-to-disk)

- [Choose a project generator for your team](/howto/choose-a-project-generator-for-your-team)

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

[^1]: jostraca's [tutorial](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/tutorial.md)
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.