How-to › Ship an SDK

How to propagate a template change to every SDK repo that uses it#

Release a template fix as a package version, dry-run it in every SDK repository, land it as a branch in each, and treat a repository with no diff as forked.

Audience
Platform team
Level
advanced
Topic
Customize a generator without forking
Languages
TypeScript
Verified

Read first: Package a customization several SDK projects can install

Your request-id template sends one id on every call, and you fixed it in one repository. Five repositories need the fix. One edited that template locally, one copied it by hand, and one installs it from a checkout nobody pulls. A rollout that reports success in each cannot tell you which repositories received the change.

What you get

You will end up with a template fix released as a package version, rolled out as one branch per repository, and a report that sorts every repository into five outcomes. This is for you if you own templates that several SDK repositories generate from.

Short answer

Release the fix as a version of an sdkgen package, then script the rollout. In each repository, install the release and run voxgig-sdkgen package update with --dryrun, then run it for real on a branch, regenerate, and diff the generated SDK. Sort each result into an expected diff, a conflict, a refusal, or no diff, and chase every no-diff repository, because its update reported success.

You will need

Node 22 or later, git, and two or more SDK repositories generated from one set of templates. Verified 2026-11-22 against @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, Kiota 1.38.0 and 1.39.0, and git 2.43.0. Packaging the template is covered in package a customization several SDK projects can install.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Fern generatorVersion and ReplayFern generates the SDKs and you want regeneration pull requestsNo templates of your own, and Replay’s custom code needs the Enterprise planYou own the template, not the generator
git subtree of the template folderTemplates live in their own repository and every SDK repository vendors themA version only as a commit hash, and a hand copy it refuses to pull intoYou need a changelog and a rollback per release
Kiota update and kiota-lock.jsonThe change is a Kiota release, and every client records its parameters in a lockNo templates, and an update that removes hand edits while reporting successYour change lives in a template you wrote
scripted regeneration pull requestsAny of these, driven across every repository with one scriptA script to own, and a classifier that must know what the change looks likeTwo repositories, where a person reads both diffs
sdkgen package updatesdkgen projects that install a shared package from npmEvery fix waits for a release, and its dry run missed the one conflictYou need the fix in a repository within the hour

Voxgig maintains sdkgen. The page compares its package update with four other ways to ship a fix.

A versioned package gives you a changelog, a rollback and a copy record in each repository, at the price of a release for every change. A git subtree pull is instant and records only a commit. Kiota and Fern have no templates for you to change, so their rollout is a generator version, and the script’s job is the same: classify each repository’s diff before anyone merges it.

Release the fix as a package version

The fix is one line of the feature’s template, in @acme/sdkgen-trace 1.1.0. 1.0.0 minted an id in init, so every call carried the same one.

    spec.headers = spec.headers || {}
    // 1.1.0: one id per request. 1.0.0 minted one id in init and sent it on every call.
    spec.headers[this._options.header || 'X-Request-Id'] = randomUUID()
  }
}

generate.sh packs both versions with npm pack and sets up five scratch repositories on 1.0.0. orders and billing install from npm. catalog does too, then edits the line the fix touches. ledger copied the feature into its own .sdk, and returns added it from a checkout beside the project by a relative path.

Dry-run, branch, and classify every repository

rollout.mjs installs the release in each repository and runs the update with --dryrun, then puts every tracked file back. Then it creates rollout/acme-sdkgen-trace-1.1.0 in each, updates for real, regenerates, and passes the exit status and git diff -- ts to the classifier.

  const { update, diff } = result
  if (update.exit !== 0) {
    const conflict = /cannot take the incoming copy/.test(update.error ?? '')
    return { outcome: conflict ? 'conflict' : 'refused', detail: (update.error ?? '').split('\n')[0] }
  }
  if (diff.trim() === '') return { outcome: 'no diff', detail: 'treat as forked or stale until shown otherwise' }

The rollout ran once, from generate.sh. report.mjs classifies the committed diffs again and prints what each repository reported.

node report.mjs
@acme/sdkgen-trace 1.1.0, branch rollout/acme-sdkgen-trace-1.1.0
repo         dry run  update  SDK files changed  outcome
orders-sdk   exit 0   exit 0  3                  expected diff
billing-sdk  exit 0   exit 0  3                  expected diff
catalog-sdk  exit 0   exit 1  0                  conflict
ledger-sdk   exit 1   exit 1  0                  refused
returns-sdk  exit 0   exit 0  0                  no diff

which release each says it has: package list, then the copy record in .sdk/log/copies.jsonl
orders-sdk   before: @acme/sdkgen-trace@1.0.0, copies 1.0.0   after: @acme/sdkgen-trace@1.1.0, copies 1.1.0
billing-sdk  before: @acme/sdkgen-trace@1.0.0, copies 1.0.0   after: @acme/sdkgen-trace@1.1.0, copies 1.1.0
catalog-sdk  before: @acme/sdkgen-trace@1.0.0, copies 1.0.0   after: @acme/sdkgen-trace@1.1.0, copies 1.0.0
ledger-sdk   before: (unrecorded), copies none recorded       after: (unrecorded), copies none recorded
returns-sdk  before: @acme/sdkgen-trace@1.0.0, copies 1.0.0   after: @acme/sdkgen-trace@1.0.0, copies 1.0.0

orders-sdk on 1.0.0: two calls, same request id: true
orders-sdk on 1.1.0: two calls, same request id: false

The two npm repositories changed three generated files: the feature and two documents that print its version. A compiled orders SDK sent a fresh id per call afterwards.

catalog is the edited one. It exited 0 on a dry run that printed 1 locally-changed file(s) will take the update by merge. The real update printed 1 locally changed file(s) cannot take the incoming copy, so nothing was changed, exited 1, and named log/conflict/ as the place of the incoming copy. ledger was refused with “Nothing installed from @acme/sdkgen-trace”, because package list shows its feature as (unrecorded) and the copy record has no entry for it. returns printed “updated” and changed nothing, because its checkout still holds 1.0.0.

Roll out the same fix from a template repository or a Kiota release

The same release went into four repositories as a git subtree of the template folder, and Kiota moved three generated clients from 1.38.0 to 1.39.0 with kiota update.

node others.mjs
git subtree pull --squash of the template folder, v1.0.0 -> v1.1.0
  orders   exit 0  merged                                                   release v1.1.0
  billing  exit 0  merged                                                   release v1.1.0
  catalog  exit 1  conflict in acmetrace/AcmetraceFeature.ts                release v1.0.0
  returns  exit 1  fatal: can't squash-merge: 'acmetrace' was never added.  release none recorded
kiota update with 1.39.0, on clients generated by 1.38.0
  orders   exit 0  Update of 1 clients completed successfully  lock 1.39.0  changed: client/kiota-lock.json
  billing  exit 0  Update of 1 clients completed successfully  lock 1.39.0  changed: client/kiota-lock.json
  catalog  exit 0  Update of 1 clients completed successfully  lock 1.39.0  changed: client/kiota-lock.json, client/models/index.ts
           removed: // catalog: a hand edit to a generated file

git subtree reports its conflict and its hand copy, but its record of a version is a commit hash in the squash message, mapped to a tag here.1 Kiota builds code from a code model rather than templates, as its design page explains, so a Kiota rollout is a generator version. It writes kiotaVersion into each kiota-lock.json, which answers which repository has which release, and on this document 1.39.0 changed nothing else. In the edited repository it removed the hand edit and still reported success, so only the diff shows it.2

Fern’s documentation index lists no templates of your own either, only custom code. Its current configuration, sdk-config.yml, runs the newest generators unless a target pins generatorVersion, and the legacy generators.yml moves with fern generator upgrade. Local edits survive through Replay, which reports a conflict in the regeneration pull request, or .fernignore, whose files stop receiving updates at all. The pricing page puts custom code on the Enterprise plan.

Check it worked

The suite classifies the committed diffs and checks each record.

node --test rollout.test.mjs
1..11
# tests 11
# suites 0
# pass 11
# fail 0
# cancelled 0
# skipped 0
# todo 0

One test feeds the classifier three neighbors of the orders diff and expects unexpected diff for each. One turns the removed line into context, one adds a changed line to the feature, and one adds a changed file.

When it goes wrong

The dry run is green and the real run conflicts. In 4.44.3, withCopyMerge in dist/helpers/copymerge.js skips the merge guard on a dry run, so --dryrun reports the planned merge without trying it. Treat a dry run as a check of which files would move, then let the real run on a branch decide. The refusal names two ways on: fold the change in by hand and rerun with --keep, or take the release with --force.

A repository names a release it does not have. In catalog’s working copy after the refusal, package list reported 1.1.0, the version npm had installed, while .sdk/log/copies.jsonl still said 1.0.0. Read the copy record when you audit versions.

Every generate in returns warns that 1.0.0 “has changed since they were copied” even though the checkout never moved, from the first generate on. The same checkout added by its absolute path gave no warning, so the relative path causes it, and the update does not clear it. doctor printed .sdk matches the scaffold and exited 0. Pull the checkout before every rollout, or install from npm instead.

When not to do this

Do not package a template that two repositories share. A release, a changelog, and a copy record cost more than reading two diffs, and a git subtree covers that case.

Do not merge a rollout branch whose outcome is no diff. In this run returns printed success with a stale source. On a Kiota release that changes no output, no diff is the right result, so tell the classifier what the release changes.

Do not use sdkgen’s package update for a fix that must reach a repository today. Kiota, Fern, and a git subtree pull move as soon as you run them, and Kiota’s lock records the version without a release of your own. The newest sdkgen and apidef releases gave the same dry run, conflict, and warning.

Last verified

Verified 2026-11-22 against Node 22.23.5, git 2.43.0, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, and Kiota 1.38.0 and 1.39.0, with the catalog and returns repositories run again on @voxgig/sdkgen 4.45.0 and @voxgig/apidef 8.33.1. generate.sh ran every rollout in scratch repositories, twice with the same records, and committed what the commands read. Fern was not run, since it generates on its own service or in Docker: its version settings, Replay and plans come from its documentation as fetched that day.

Footnotes

  1. The git subtree documentation explains --squash with an example of its own: people rarely want to see every change between v1.0 and v1.1 of the library they use. It adds that --squash lets a project switch back and forth between versions rather than strictly forward, which makes a rollback one more pull. ↩︎ Back to text

  2. Kiota’s support page targets minor releases at the first Tuesday of every month. Its changelog dates 1.38.0 to November 2, 2026, a Monday, and 1.39.0 to November 17, so the month’s first Tuesday fell between the two releases this page ran. ↩︎ 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.