A package adds the Haskell target your SDK project was missing, and the generate that follows
also rewrites the TypeScript README, the root README, the Makefile, AGENTS.md and SUMMARY.md.
The pull request also adds 97 files for the target, so a reviewer skims past those five
rewrites. The package’s next release can change them again.
What you get
You will end up with a third party package installed at a pinned version and a list of every file it wrote. A test fails when the package writes more than you approved. This is for you if your team installs generator extensions that other people maintain.
Short answer
In sdkgen, install the package with npm --save-exact, run package check on it, and run
package add with -y, which lists every file it would write. Then add it, generate, and diff
the project against a generation from before the install. Files the package had no reason to
change, such as another language’s README, are the finding. Kiota and Speakeasy install no
generator packages: pin the tool and diff its output.
You will need
Node 22 or later and a generated SDK project you can regenerate. The sample scaffolds the
Bookshelf API with sdkgen, adds the Haskell target from @voxgig/sdkgen-langpack, and generates
a TypeScript client with Kiota three times.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Kiota serializer packages | You need a wire format Kiota’s default serializers do not cover | Naming one serializer drops every default writer, and the package is a runtime dependency of each client | You need a language Kiota has no writer for |
| OpenAPI Generator custom generator jar | A whole generator someone wrote in Java, run beside the stock ones | A Java build of the jar, and a class path naming it beside the CLI jar on every run | The change is a template or two, which -t covers |
| sdkgen packages | Your project is sdkgen and someone ships the target or feature you need | Each 0.0.x release to vet again, and shared output files the package regenerates | Your SDK comes from another generator, which cannot read the package |
| Speakeasy speakeasyVersion pin | Speakeasy generates the SDK and you want generator changes on your schedule | A pinned CLI also misses generator fixes until someone moves the pin by hand | You want upgrades tried for you, which the default latest does |
Voxgig maintains sdkgen. It is one of four options here, not the recommendation.
The sdkgen row is the only one where a third party package installs into the generator. Kiota’s extension point is a runtime library the client imports, and OpenAPI Generator’s is a jar on the class path. Speakeasy’s workflow file has no field for a generator package, so its lever is the version of the whole tool.
Vet the package before it writes anything
Generate once before the install and keep a listing of every file with its hash. Then install
with npm, check the package, and ask sdkgen for a dry run. generate.sh records each step.
cd bookshelf-sdk/.sdk
npm install --save-dev --save-exact --no-audit --no-fund @voxgig/sdkgen-langpack@0.0.16
npx voxgig-sdkgen package check node_modules/@voxgig/sdkgen-langpack 2>&1 | log > "$OUT/package-check.txt"
npx voxgig-sdkgen -y package add @voxgig/sdkgen-langpack --only target:haskell 2>&1 | log > "$OUT/dry-run.txt"
npx voxgig-sdkgen package add @voxgig/sdkgen-langpack --only target:haskell 2>&1 | log > "$OUT/package-add.txt"
npx voxgig-sdkgen package list 2>&1 | log > "$OUT/package-list.txt"
npm run generate
npm fetches and sdkgen installs, as two steps. The
CLI reference says
package check exits non-zero on any error finding, and this package had none. --only installs
one of the three targets the package provides. -y lists each file the add would write and
writes none of them. vet.mjs reads what the run kept.
node vet.mjs
@voxgig/sdkgen-langpack 0.0.16, needs sdkgen >=4.44.3
provides target: dart, haskell, lean
pinned in .sdk/package.json as "0.0.16"
dry run of package add --only target:haskell: 65 paths in .sdk/
outside the package's own folders: model/target/target-index.aontu
generate before and after: 97 added, 10 changed, 0 removed
added 1 .sdk/model/target/haskell.aontu
added 22 .sdk/src/cmp/haskell/
added 41 .sdk/tm/haskell/
added 33 haskell/
changed .sdk/doc/qa/styles/config/vocabularies/Docgen/accept.txt
changed .sdk/model/sdk.json
changed .sdk/model/target/target-index.aontu
changed .sdk/package-lock.json
changed .sdk/package.json
changed AGENTS.md <- generated output, not haskell/
changed Makefile <- generated output, not haskell/
changed README.md <- generated output, not haskell/
changed SUMMARY.md <- generated output, not haskell/
changed ts/README.md <- generated output, not haskell/
The dry run was accurate about .sdk/: everything it listed sits in the package’s own folders,
plus one shared index line. It says nothing about generated output, because the add writes none.
That is what the second generation shows. Five files outside haskell/ changed. sdkgen writes
the root README, AGENTS.md and the Makefile from every active target, and docgen’s summary
edition writes SUMMARY.md the same way, so a second target edits all four. ts/README.md
gained a three-line note pointing at the other languages, written by sdkgen’s own helper rather
than by the package.
None of the five is wrong. Each is a change nobody asked the package for, and a diff of the whole project is the only step that shows them before review does.
package list reads the provenance recorded in the model files, so it names the version each
item came from:
cat runs/package-list.txt
INFO: sdkgen package-list-entry @voxgig/docgen@0.30.9: edition `github-pages`, edition `summary`
INFO: sdkgen package-list-entry @voxgig/sdkgen@4.44.3: feature `test`, target `ts`
INFO: sdkgen package-list-entry @voxgig/sdkgen-langpack@0.0.16: target `haskell`
INFO: sdkgen package-list-end 3 package(s)
--save-exact wrote 0.0.16 into .sdk/package.json. The scaffold wrote ~4.44.3 for sdkgen
itself, which accepts any later 4.44 patch on the next fresh install.1
Keep a customized template through the next add
A package’s templates land in .sdk/tm/<target>/, and editing one is how you adjust its output.
The sample appends one line to .sdk/tm/haskell/Makefile, runs doctor, then adds the package
again, once plainly and once with --force.
node pitfall.mjs
edited after install: .sdk/tm/haskell/Makefile
doctor: CUSTOMIZED (an add merges its updates into it): tm/haskell/Makefile
package add again: package add @voxgig/sdkgen-langpack: merged the incoming copy into 1 locally changed file(s): tm/haskell/Makefile
the edit survives: yes
package add again with --force
the edit survives: no
the log names the file: no
The default merges, and says so. --force takes the package’s copy without naming the
Makefile, although the CLI reference describes --force as listing what it discarded. Run
doctor before any add with --force, and keep its list of customized files in the pull request.
Pin the tool in Kiota and Speakeasy
Kiota installs no generator packages. The option that writes someone else’s package into the
generated code is the serializer list: --serializer and --deserializer name the classes the
client registers, and their package becomes a dependency of the client. The sample generated the
TypeScript client three times: with the defaults, with one third party pair, and with JSON kept
beside it.
node kiota.mjs
default: kiota-lock.json kiotaVersion 1.38.0
serializers JsonSerializationWriterFactory, TextSerializationWriterFactory, FormSerializationWriterFactory, MultipartSerializationWriterFactory
deserializers JsonParseNodeFactory, TextParseNodeFactory, FormParseNodeFactory
imports @microsoft/kiota-serialization-form, @microsoft/kiota-serialization-json, @microsoft/kiota-serialization-multipart, @microsoft/kiota-serialization-text
cbor: kiota-lock.json kiotaVersion 1.38.0
serializers CborSerializationWriterFactory
deserializers CborParseNodeFactory
imports @contoso/kiota-serialization-cbor
both: kiota-lock.json kiotaVersion 1.38.0
serializers JsonSerializationWriterFactory, CborSerializationWriterFactory
deserializers JsonParseNodeFactory, TextParseNodeFactory, FormParseNodeFactory
imports @contoso/kiota-serialization-cbor, @microsoft/kiota-serialization-form, @microsoft/kiota-serialization-json, @microsoft/kiota-serialization-text
In the second client, two options replaced all seven default factories, so it can no longer
write or read JSON. Each option replaces only its own list. The third client named two serializers
and no deserializer, so it kept the three default readers and lost the text, form, and multipart
writers. Name every default you still need beside the extra class. Write the value as
--serializer=@scope/...: given as a separate word, a value starting with @ failed with
Error reading response file.2 kiota-lock.json records kiotaVersion and the serializer list, so commit it and pin the binary
by version and hash, as generate.sh does.
Speakeasy was not run here. Its workflow file
takes speakeasyVersion as latest, pinned, or an exact version. latest, the default,
attempts each generator upgrade and falls back to the last successful version when generation
fails. An exact version holds generator changes until you move it, and a diff of the two
generations shows the change before you commit it. Speakeasy’s
versioning page adds that a generator
release can bump your SDK’s own version.
Check it worked
vet.test.mjs holds ten tests over the committed runs. One fails if the dry run writes outside the package folders
beyond the target index, another if the changed output files are not exactly
AGENTS.md, Makefile, README.md, SUMMARY.md and ts/README.md.
node --test vet.test.mjs
1..10
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0
In your own project, keep the list of changed output files in the test. A package release that touches one more file then fails it.
When it goes wrong
npm run generate warns that this run generates from older templates. npm moved the package,
but generation renders from the copies in .sdk/, which still match the version you added. The
sample moved the langpack to 0.0.15 with npm, and three copies differed. Run
npx voxgig-sdkgen package update @voxgig/sdkgen-langpack --no-fetch, which refreshed all three.
The diff is hundreds of lines. You hashed build caches along with the project. Leave out
node_modules, .sdk/dist, .sdk/log and every .jostraca folder, as generate.sh does,
because those change on every run.
When not to do this
Do not install a package to save writing a target you will need to change heavily. The
customized copies merge on every update, and each merge is a review you inherit on the
package’s release cadence. Fork it into .sdk/ as your own target instead.
Do not reach for sdkgen packages if your SDK comes from another generator. A Kiota or Speakeasy project cannot read one, and pinning that tool’s version plus a diff gives you the same review point. Kiota is the better choice when you need a client whose wire format is a runtime library you can swap later, since its serializer packages are plain dependencies of the generated code. Speakeasy is the better choice when you would rather its service try each generator upgrade and roll back failures than vet releases yourself.
Do not keep a package you have not pinned. A range resolves to a different release on the next fresh install, and the diff you reviewed no longer describes the output.
Related how-tos
Last verified
Verified 2026-11-20 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen
4.44.3, @voxgig/docgen 0.30.9, @voxgig/sdkgen-langpack 0.0.16 and Kiota 1.38.0. The scaffold,
both generations and the four Kiota runs happened once, in generate.sh; their logs and listings
are committed under runs/ and kiota/, and the commands shown read them. Speakeasy was not run. Its options come from its documentation.
Footnotes
-
npm’s
save-prefixdefaults to a caret, and node-semver’s README gives a caret on a0.0.xversion no room at all:^0.0.3means at least 0.0.3 and below 0.0.4. npm’s default range and--save-exacttherefore agree for this package, and disagree for the generator beside it, whose tilde range admits every later patch of 4.44. ↩︎ Back to text -
A response file is a file of command-line tokens. The
System.CommandLinesyntax page says to use one by entering its name prefixed by an @ sign wherever in the line the tokens belong. npm scopes begin with the same character, which is how a package name came to be opened as a file. ↩︎ Back to text