You change one line of a TypeScript template and run npm run generate, which rebuilds five
language targets and a test model before the line reaches ts/. Every check of the edit waits
for languages you are not touching. The flag documented as a dry run writes the files anyway, so
it cannot try an edit without overwriting the output.
What you get
You will end up with an edit loop that regenerates one target or regenerates on save. Two CI checks fail on a partial-generation switch in a committed file and on a missing generated file. This is for you if you customize a generator’s templates.
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 | 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 | 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 | 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:
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:
cat records/sdkgen-scaffolded.txt
@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 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:
cat records/swagger-codegen.txt
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 feature
keeps through a three-way merge.
speakeasy 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 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:
node guard.mjs ci/project.aontu ci/regenerate.sh; echo "exit $?"
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:
cat records/expect.txt
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:
node --test loop.test.mjs | tail -8
# 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
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.
Footnotes
-
The selective generation page ends its examples with the sentence that, when using selective generation, only the templates needed for the specific generation will be used. For
typescript-fetchthat holds for the file. The template forapi.tsran, but the data for its model section comes with-Dmodels, which was not set. ↩︎ Back to text