How-to › Ship an SDK

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.

Audience
API producer
Level
intermediate
Topic
Customize a generator without forking
Languages
TypeScript
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
sdkgen target switch and watch modeSeveral targets, and you edit the templates of oneA model line to remove before committing, and output for other targets left stale meanwhileYour edit spans every target, so a full run is the loop
Speakeasy per-target runsA Speakeasy workflow with several targets in workflow.yamlNo template overrides to edit, and a platform login before the CLI runsYou need to change the generated code’s shape, not its configuration
Swagger Codegen selective generationOne client language, and templates you override with -tSelected files are rendered from partial data unless you also select what feeds themThe 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.

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

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