# How to install a generator package and check what it changes

> Install a third party generator package, read what it will write before it writes, diff a generation from before and after, and pin the version you vetted.

Source: https://voxgig.com/howto/install-and-vet-a-third-party-generator-package

- Audience: platform-team
- Level: intermediate
- Languages: typescript
- Verified: 2026-11-20
- Published: 2026-11-20

## 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](https://learn.microsoft.com/en-us/openapi/kiota/using) | 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](https://openapi-generator.tech/docs/customization/) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/use-an-sdkgen-package.md) | 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](https://www.speakeasy.com/docs/speakeasy-reference/workflow-file) | 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.

```bash title="generate.sh"
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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/cli.md) 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.

```bash
node vet.mjs
```

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

```bash
cat runs/package-list.txt
```

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

```bash
node pitfall.mjs
```

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

```bash
node kiota.mjs
```

```text output
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](https://www.speakeasy.com/docs/speakeasy-reference/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](https://www.speakeasy.com/docs/sdks/manage/versioning) 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`.

```bash
node --test vet.test.mjs
```

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

- [Package a customization several SDK projects can install](/howto/package-a-shared-generator-customisation)

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

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Evaluate a third-party SDK before you depend on it](/howto/evaluate-a-third-party-sdk)

- [Add a custom target to a generation run in your own repo](/howto/add-a-custom-target-without-contributing-upstream)

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

[^1]: npm's [`save-prefix`](https://docs.npmjs.com/cli/v10/using-npm/config/) defaults to a caret,
and [node-semver's README](https://github.com/npm/node-semver) gives a caret on a `0.0.x`
version no room at all: `^0.0.3` means at least 0.0.3 and below 0.0.4. npm's default range and
[`--save-exact`](https://docs.npmjs.com/cli/v10/commands/npm-install/) therefore agree for this
package, and disagree for the generator beside it, whose tilde range admits every later patch of 4.44.

[^2]: A response file is a file of command-line tokens. The
[`System.CommandLine` syntax page](https://learn.microsoft.com/en-us/dotnet/standard/commandline/syntax)
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.