# How to shorten the regenerate loop while you edit a template

> Regenerate one target or run a watcher while you edit a generator template, then finish with a full run and CI checks for leftover switches and missing files.

Source: https://voxgig.com/howto/shorten-the-regenerate-loop-while-editing-templates

- Audience: api-producer
- Level: intermediate
- Languages: typescript
- Verified: 2026-11-21
- Published: 2026-11-21

## Short answer

In sdkgen, keep npm run watch-generate running, or run the model step alone with the other targets switched off in .sdk/model/project.aontu. The dry-run flag still writes, and --only and the debug levels narrow nothing. In Swagger Codegen, pass -Dmodels, -Dapis and -DsupportingFiles together. In Speakeasy, use speakeasy run -t. Then regenerate in full into empty directories, and fail CI on a leftover switch or a missing file.

---
## You will need

Node 22 or later, a generated SDK project you can regenerate, and Java 11 or later for Swagger
Codegen. Verified 2026-11-21 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9,
`@voxgig/sdkgen` 4.44.3 and 4.45.0, `@voxgig/model` 12.0.2, and `swagger-codegen-cli` 3.0.85 on
OpenJDK 21. The sample project is the Bookshelf API with five targets: `ts`, `py`, `go`, `rb`
and `php`.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [sdkgen target switch and watch mode](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | Several targets, and you edit the templates of one | A model line to remove before committing, and output for other targets left stale meanwhile | Your edit spans every target, so a full run is the loop |
| [Speakeasy per-target runs](https://www.speakeasy.com/docs/speakeasy-reference/cli/run) | A Speakeasy workflow with several targets in `workflow.yaml` | No template overrides to edit, and a platform login before the CLI runs | You need to change the generated code's shape, not its configuration |
| [Swagger Codegen selective generation](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generation-selective/) | One client language, and templates you override with `-t` | Selected files are rendered from partial data unless you also select what feeds them | The client writes many files and you need them all to check an edit |

The sdkgen switch narrows by target, which matches how its templates are laid out, one tree per
language. Swagger Codegen narrows by kind of file, which is finer and easier to get wrong: a
supporting file rendered without its models looked plausible here and lacked them. Speakeasy
narrows by target too, but its loop edits configuration rather than templates.

Voxgig maintains sdkgen; the table lists it as one of three options, in alphabetical order.

## Run the model step for one target while you edit

The model reference documents `main.kit.target.<t>.active` as whether the target is generated.
Append the other targets, switched off, to the project overlay for the length of the edit:

```aontu title="loop.aontu"
main: kit: target: { py: active: false, go: active: false, rb: active: false, php: active: false }
```

`npm run generate` runs four steps, as `records/scripts.txt` shows: the docgen preparation, a TypeScript build of `.sdk/src`, the
model build that writes the SDKs, and a build of the test model. A template under `.sdk/tm` needs
only the third, `npx voxgig-model model/sdk.aontu`. A component under `.sdk/src/cmp` also needs the
build, `npm run build`. `npm run watch-generate` keeps that third step running and rebuilds when a
watched file changes, a template under `.sdk/tm` included.

`records/timings.txt` holds the measurements, each the median of five runs on a shared four-core
sandbox, so read them as one machine's ratios. `npm run generate` for five targets took 6.2 s.
The model step for one target took 1.4 s, and the watcher wrote the edited file 0.5 s after the
template was saved.

## Check what each flag writes

`record.sh` edited a `ts` template and a `py` template, then tried each lever:

```bash
cat records/sdkgen-scaffolded.txt
```

```text output
@voxgig/sdkgen 4.44.3, @voxgig/model 12.0.2
loop.aontu in project.aontu, then voxgig-model model/sdk.aontu
  ts template edit in ts/: yes   py template edit in py/: no
  npm run generate, loop.aontu still there: exit 0, py template edit in py/: no, warnings: 0
  voxgig-sdkgen doctor: exit 0
loop.aontu removed, npm run generate: py template edit in py/: yes
npm run dry-generate after a ts template edit: ts/ written
voxgig-model --help on -y: --dryrun Perform a dry run, where no files are modified.
voxgig-model -y model/sdk.aontu after a ts template edit: ts/ written
voxgig-sdkgen --only no-such:thing target add ts: exit 0, lines naming --only: 0
voxgig-model -g info: 51 log lines, lines naming Spec.ts: 0, lines naming a path under tm/: 0
voxgig-model -g debug: 262 log lines, lines naming Spec.ts: 0, lines naming a path under tm/: 0
voxgig-model -g trace: 262 log lines, lines naming Spec.ts: 0, lines naming a path under tm/: 0
  .sdk/log/generated.jsonl, last entry naming ts/src/Spec.ts, maps it to: Root/Main/Main@ts
```

The switch works and stays silent. A full `npm run generate` with `loop.aontu` still in place left
the `py` edit out of `py/`, exited 0, warned of nothing, and `doctor` agreed.

The other levers do less than their names. Both dry runs wrote `ts/`, although the help of
`voxgig-model` says no files are modified: `makeBuild` hands the generator only the model's logger
and debug level, so the dry-run option never reaches it. The
[CLI reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/cli.md) documents
`--only` for `package add` alone, and `target add` accepted a nonsense value without a word. The
debug levels add lines about the model but name no path under `tm/`. Which component wrote
a file is in `.sdk/log/generated.jsonl`. The run on 4.45.0 printed the same lines, apart from one
more line at the info level.

## Narrow the run in Swagger Codegen and Speakeasy

Swagger Codegen's selective generation takes `-Dmodels`, `-Dapis` and `-DsupportingFiles`, each
with an optional list of names. The `typescript-fetch` client writes its models and its API classes
into `api.ts`, a supporting file, so `-Dmodels` alone writes nothing. Selecting `api.ts` renders it
from whatever data the other two properties let in:

```bash
cat records/swagger-codegen.txt
```

```text output
swagger-codegen-cli 3.0.85, typescript-fetch, -t with modelGeneric.mustache edited
full run: .gitignore .swagger-codegen-ignore .swagger-codegen/VERSION api.ts api_test.spec.ts configuration.ts custom.d.ts git_push.sh index.ts
  the edit in api.ts: yes
-Dmodels into an empty directory: exit 0, files: none
-DsupportingFiles=api.ts into an empty directory: .swagger-codegen-ignore .swagger-codegen/VERSION api.ts
  api.ts: 79 lines, the edit: no, same as the full run: no
-Dmodels -DsupportingFiles=api.ts into an empty directory: .swagger-codegen-ignore .swagger-codegen/VERSION api.ts
  api.ts: 111 lines, the edit: yes, same as the full run: no
-Dapis -DsupportingFiles=api.ts into an empty directory: .swagger-codegen-ignore .swagger-codegen/VERSION api.ts
  api.ts: 442 lines, the edit: no, same as the full run: no
-Dmodels -Dapis -DsupportingFiles=api.ts into an empty directory: .swagger-codegen-ignore .swagger-codegen/VERSION api.ts
  api.ts: 474 lines, the edit: yes, same as the full run: yes
files the full run wrote that the last run did not: .gitignore api_test.spec.ts configuration.ts custom.d.ts git_push.sh index.ts
```

Only all three together reproduced the full `api.ts`, and every variant exited 0, so check the
files and never the exit status.[^1]

Speakeasy documents no template overrides. Its gen.yaml reference never mentions templates, and
no page in its documentation sitemap has one in its address. What you change between runs is
the document, an overlay, `gen.yaml`, hook code, or the generated files themselves, which its
[custom code](https://www.speakeasy.com/docs/sdks/customize/code/custom-code/custom-code) feature
keeps through a three-way merge.
[`speakeasy run`](https://www.speakeasy.com/docs/speakeasy-reference/cli/run) takes `-t` with a
target ID from `workflow.yaml`, `--skip-compile`, `--skip-testing`, `--skip-versioning`, and
`--minimal` to run only the steps strictly necessary to generate the SDK. Its CLI asks you to
[authenticate](https://www.speakeasy.com/docs/speakeasy-reference/cli/getting-started) with the
platform first, so it was not run here.

## Check it worked

Run the guard on the files your release job reads. Here it reads a project model and a
regenerate script left over from an edit session:

```bash
node guard.mjs ci/project.aontu ci/regenerate.sh; echo "exit $?"
```

```text output
ci/project.aontu:6: sdkgen target switched off: py, go, rb, php
ci/regenerate.sh:5: selective generation: -DsupportingFiles=api.ts
ci/regenerate.sh:7: speakeasy run narrowed: -t typescript --skip-compile
3 partial-generation switch(es): run the full generation
exit 1
```

The guard reads text, so it cannot see a switch it has no rule for. After the full run, generate
into empty output directories and check every file a full run writes is there. `record.sh` ran
`expect.mjs` that way on both generators, with each file list as the manifest:

```bash
cat records/expect.txt
```

```text output
sdkgen, every target, generated into empty directories: 419 files, listed in records/sdkgen-files.txt
loop.aontu still there, generated into empty directories, node expect.mjs: exit 1, 324 of 419 expected files missing: run the full generation
  missing, by directory: go 82, php 76, py 88, rb 78
loop.aontu removed, generated into empty directories, node expect.mjs: exit 0, 419 expected files present
swagger-codegen, the full run, node expect.mjs: exit 0, 9 expected files present
swagger-codegen, -Dmodels -Dapis -DsupportingFiles=api.ts, node expect.mjs: exit 1, 6 of 9 expected files missing: run the full generation
```

The clean copies in `ci/clean/` pass the guard. The suite checks it against each switch alone,
across a line continuation, and inside a comment. It feeds `expect.mjs` a removed file, an empty
manifest and a path outside the directory, and checks every record line the page relies on:

```bash
node --test loop.test.mjs | tail -8
```

```text output
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 564.894705
```

## When it goes wrong

A template edit never reaches a target. `loop.aontu` was still in the project overlay, which
generates no warning. Remove the lines, run `npm run generate`, and keep the guard in CI.

A dry run overwrites your output. In this release `npm run dry-generate` and `voxgig-model -y`
both write the SDK. Copy the output first, or preview a regeneration as a diff instead.

`api.ts` loses its models after a selective Swagger Codegen run. You selected the supporting file
without `-Dmodels` and `-Dapis`. Pass all three, and compare one run with a full run's output
before you trust the shortcut.

## When not to do this

Do not shorten the loop for an edit that touches every target, such as a shared component. The
full run is the loop there, and a partial one hides breakage in the targets it skips.

Do not commit any of these switches. A release built from a partial run ships a stale target with
exit 0, which is why the guard exists. Speakeasy's per-target runs are the safer choice when each
target already has its own CI job, because `-t` there matches how the work is split.

Do not expect sdkgen's switch to narrow further than a target. Swagger Codegen is the better fit
for one client language and a few templates, because it narrows by file and, once the three
properties are right, regenerates one template's output alone.

## Related how-tos

- [Find which template produced a generated file](/howto/find-which-template-produced-a-generated-file)

- [Preview a regeneration as a diff before writing files](/howto/preview-a-regeneration-as-a-diff)

- [Rename a generated SDK method without editing the output](/howto/rename-generated-methods-without-editing-output)

- [Fail a build when a generator customization becomes a fork](/howto/audit-generator-customisations-for-drift)

- [Propagate a template change to every SDK repo that uses it](/howto/propagate-a-template-change-across-sdk-repos)

## Last verified

Verified 2026-11-21 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen`
4.44.3 and 4.45.0, `@voxgig/model` 12.0.2, and `swagger-codegen-cli` 3.0.85 on OpenJDK 21.0.13.
`record.sh` ran every generator and committed only its records; the records and timings on this
page are from its run of 2026-11-22. The timings are one shared machine's measurements on one day.
Speakeasy was not run, and its options were read from its CLI reference.

[^1]: The [selective generation page](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generation-selective/)
ends its examples with the sentence that, when using selective generation, only the templates
needed for the specific generation will be used. For `typescript-fetch` that holds for the file.
The template for `api.ts` ran, but the data for its model section comes with `-Dmodels`, which
was not set.