How-to › Ship an SDK

How to take over a bundled SDK target and maintain it yourself#

Copy a bundled sdkgen target into a package you own, point the project at it, and take upstream fixes by diffing the release you branched from against the next one.

Audience
Library maintainer
Level
advanced
Topic
Customize a generator without forking
Languages
TypeScript
Verified

Read first: Add a custom target to a generation run in your own repo

Every SDK your company publishes must declare Apache-2.0 and a private registry, and the generator’s TypeScript target writes "license": "MIT" into package.json from code, not from a setting. Twelve SDK repositories each carry the same edit to their copy of the target. Each one merges the next generator release on its own, and one of them gets it wrong.

What you get

You will end up with the TypeScript target in a package you own, a record of the sdkgen release it follows, and a tested way to bring one upstream fix across. This is for you if several projects need the same change to a bundled target.

Short answer

Copy the bundled target’s three trees from the sdkgen release you are on into a package of your own, beside the project, and record that release in the package. Point the project at it with voxgig-sdkgen target add <package>/ts, because a same-name package add is refused. To take an upstream fix, diff the target between the recorded release and the new one, apply that patch to the package, and run package update --no-fetch.

You will need

Node 22 or later, an sdkgen project, and a change the bundled target cannot be configured to make. Verified 2026-11-21 against @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3 and the 4.44.0 tarball, and Swagger Codegen 3.0.84 and 3.0.85. The project is the Bookshelf document with a ts target. The change is two lines in one component, Package_ts.ts, which hardcodes the licence of the generated package.json.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Fern .fernignore and ReplayFern generates the SDK and the change is to its outputEdits land in output files, and the generator itself is not yours to changeYou need the change in every SDK the generator writes
OpenAPI Generator language class forkTemplates cannot reach the change, and a Java build is acceptableA Java module to build, and every upstream change to the class to port by handOne template override would carry the change
sdkgen bundled target with its copy editedOne project needs the changeEach project carries its own edit, merged again on every generator updateSeveral projects need the same change
sdkgen target in a package of your ownSeveral projects need one changed targetEvery upstream fix to that target reaches you only when you port itOne project, or a change one copy edit carries
Swagger Codegen custom templatesSwagger Codegen generates the SDK and a template holds the changeA template directory to diff against each release’s bundled templatesThe change is in the language class, not a template

Voxgig maintains sdkgen, the subject of this page. Two of the five rows are sdkgen routes, and the decision between them is the first step below.

The copy edit is the cheapest change and keeps upstream fixes arriving by merge. A package of your own is one edit for every project, and upstream fixes stop arriving on their own. Swagger Codegen’s -t override needs only the template you changed, and its cost moves to diffing templates per release.

Decide from the diff before you move anything

Make the change in the project’s own copy first, under .sdk/src/cmp/ts/, and run npx voxgig-sdkgen doctor. In merge mode, the default, doctor lists each file you changed as customized, and a later package update @voxgig/sdkgen merges upstream changes into it, as the copy model in the table’s third row describes. The last block of the output below is this route.

The diff is the decision. One changed file in one project stays a copy edit. One changed file in twelve projects is twelve merges per release, which is what a package of your own removes.

Copy the target into a package of your own

A package is a folder beside the project, never inside it: sdkgen’s guide to using a package says an ext/ beside .sdk is refused. It holds the three trees the target is made of, model/target/ts.aontu, src/cmp/ts/ and tm/ts/, copied from the release you branch from, plus a manifest. generate.sh takes them from the @voxgig/sdkgen 4.44.0 tarball and applies the local change as a patch.

diff -ruN a/.sdk/src/cmp/ts/Package_ts.ts b/.sdk/src/cmp/ts/Package_ts.ts
--- a/.sdk/src/cmp/ts/Package_ts.ts
+++ b/.sdk/src/cmp/ts/Package_ts.ts
@@ -106,7 +106,9 @@
     },
     author,
 
-    license: 'MIT',
+    // acme: every SDK we publish is Apache-2.0 and goes to our own registry.
+    license: 'Apache-2.0',
+    publishConfig: { registry: 'https://npm.example.com/' },
 
     // node:module strips the README examples' types under TypeScript 7.
     engines: { node: '>=22.13' },

sdkgen’s documentation calls this move migrating a bundled target into a package, and keeps “out-of-tree target” for one that generates into another repository. That guide moves the trees out of sdkgen’s own repository. This page copies them instead, so the bundled ts stays in sdkgen and the project points past it.

Keep the name ts. Renaming the target means renaming every <Cmp>_ts.ts component and the target name each passes when it reads the model, which the package guide lists as the step that is easy to miss. UPSTREAM.json is the record the next upstream diff starts from: the release the package branched from, and the release it has caught up with.

{
  "package": "@voxgig/sdkgen",
  "target": "ts",
  "version": "4.44.3",
  "branched": "4.44.0",
  "local": ["local.patch"],
  "taken": ["upstream-4.44.0-4.44.3.patch"]
}

Point the project at the package

From .sdk/, the package’s own ts is installed by reference, which replaces the bundled one:

npx voxgig-sdkgen target add ../../acme-sdkgen-ts/ts
npm run generate

logs.mjs prints what sdkgen logged at each step, from the run generate.sh recorded.

node logs.mjs
package add ../../acme-sdkgen-ts
  Voxgig SDK Generation Error: Name collision, nothing installed:
  target `ts`: already installed from @voxgig/sdkgen, and @acme/sdkgen-ts provides it too
  exit 1
target add ../../acme-sdkgen-ts/ts
  INFO target-name ts from:../../acme-sdkgen-ts/.sdk
  INFO target-done ts ref:../../acme-sdkgen-ts/ts
  WARN feature-source-shadowed test: both node_modules/@voxgig/sdkgen/project/.sdk/tm/ts and ../../acme-sdkgen-ts/.sdk/tm/ts provide source for target t ...
  exit 0
package list
  INFO package-list-entry @acme/sdkgen-ts@1.0.0: target `ts`
  INFO package-list-entry @voxgig/docgen@0.30.9: edition `github-pages`, edition `summary`
  INFO package-list-entry @voxgig/sdkgen@4.44.3: feature `test`
npm run generate, package added by a relative path
  WARN generate-copies target ts: 1 file(s) in .sdk are unchanged copies, but @acme/sdkgen-ts 1.0.0 has changed since they were copied, so this run gene ...
  exit 0
npm run generate, package added by an absolute path
  warnings: 0, exit 0
doctor after the upstream patch and package update
  INFO doctor-end .sdk matches the scaffold (0 additive, 0 customized)
doctor on the other route: the bundled target, its copy edited
  INFO doctor-finding CUSTOMIZED (an add merges its updates into it): src/cmp/ts/Package_ts.ts
  INFO doctor-end .sdk matches the scaffold (0 additive, 1 customized)
  exit 0

package list now credits ts to @acme/sdkgen-ts, so package update @voxgig/sdkgen leaves the target alone. The bundled test feature still comes from sdkgen, which is why target add warns feature-source-shadowed: that feature finds source for ts in both sdkgen’s tree and the package’s. The generated ts/ still matched the bundled target everywhere but package.json, as the next section shows.

Take an upstream fix by diffing the release you left

@voxgig/sdkgen 4.44.3 changed one file of the ts target, MakePointUtility.ts, so that an operation with one action route still checks the call’s action. Diff the target trees of the release in UPSTREAM.json and the new one, apply that patch to the package, and refresh the project with npx voxgig-sdkgen package update @acme/sdkgen-ts --no-fetch. A file both sides changed is a hand merge, and patch rejects any hunk it cannot place.1

node upstream.mjs
@voxgig/sdkgen target ts: branched at 4.44.0, upstream 4.44.3
  files in the target: 181
  changed here:        1  .sdk/src/cmp/ts/Package_ts.ts
  changed upstream:    1  .sdk/tm/ts/src/utility/MakePointUtility.ts
  changed on both:     0
  after the upstream patch, equal to 4.44.3 except the local change: true

generated ts/ compared with the bundled target, file by file
  copies          1 differ: package.json
  package-4.44.0  2 differ: package.json src/utility/MakePointUtility.ts
  package-4.44.3  1 differ: package.json

Before the patch, the package’s output lagged the bundled target by the fix. After it, the only generated difference is package.json, the change the package exists for. The copy edit reached the same output with no package at all.

Override one template in Swagger Codegen, and what Fern offers instead

Swagger Codegen 3.0.85’s typescript-fetch writes "license": "Unlicense" from package.mustache. Its generators guide takes a template folder with -t, and the run here fell back to the bundled templates for every file the folder lacked. Taking the whole generator over means a codegen module of your own, which the same guide’s meta command scaffolds.

node swagger.mjs
-t swagger-codegen/templates holds 1 file: package.mustache
  generated files that differ from the stock run: 1, package.json
  license in the custom package.json: Apache-2.0
typescript-fetch templates, 3.0.84 to 3.0.85
  templates: 15, changed: 0
  swagger-codegen-generators bundled in 3.0.84: 1.0.62
  swagger-codegen-generators bundled in 3.0.85: 1.0.62

The upstream diff for a template override is the bundled templates of two releases.2

Fern was not run, because generation needs Docker, a login, or a guest session. Its custom code page offers .fernignore for files you own and Replay, which reapplies your commits to generated output by three-way merge. The page says nothing about changing the generator itself, so the licence edit lives in each SDK repository. In sdk-config.yml, the format those pages describe rather than the legacy generators.yml, pin targets[].generatorVersion from the sdk-config reference to decide when a new generator reaches it.

Check it worked

takeover.test.mjs fails if either change stops matching its patch, or if the package falls behind the release UPSTREAM.json names. It also fails if the generated output differs anywhere the package did not mean it to.

node --test takeover.test.mjs
1..9
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 76.420711

When it goes wrong

package add refuses the package with Name collision, nothing installed. A package providing ts collides with the bundled ts. Install the target by reference, target add <package>/ts. The error’s other suggestion, --alias <name>=<alias>, installs the package’s target under another name beside the bundled one, so the project generates two TypeScript trees.

Every generate warns that one copy is outdated when the project added the package by a relative path, as sdkgen’s guide to using a package does. The warning names package update @acme/sdkgen-ts --no-fetch, and running it does not clear the warning, although doctor reports nothing outdated. With the package added by an absolute path, the same project generates with no warning, and @voxgig/sdkgen 4.45.0 behaves the same way. Add the package by an absolute path, or let CI ignore that line.

The package stops getting fixes. Nothing tells you a new sdkgen release changed ts, because the project no longer takes ts from it. Diff the target on every generator upgrade, and record the release in UPSTREAM.json.

When not to do this

Do not take over a target for a change one project needs. The copy edit in .sdk keeps upstream fixes arriving by merge, and doctor reports it as customized without failing.

Do not reach for sdkgen’s package route because a template looked hard to find. The diff that decides is the one doctor prints, and here it was one file.

Do not branch from a release you did not record. Without the version in UPSTREAM.json, the next upstream diff has no base, and every file reads as changed on both sides.

Stay with Swagger Codegen when your SDKs already come from it and the change sits in a template, because -t carries only the files you changed. Prefer Fern if you accept its generator as it ships and only the output needs your edits.

Last verified

Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3 with the 4.44.0 and 4.45.0 tarballs, @voxgig/apidef 8.32.4, Swagger Codegen 3.0.84 and 3.0.85, and OpenJDK 21.0.13. Every output block is what the command preceding it printed, from the run generate.sh recorded. Fern was not run, and .fernignore and Replay are described from its documentation.

Footnotes

  1. The fix arrived as a patch release, which Semantic Versioning 2.0.0 reserves for backward compatible bug fixes. The upstream diff for 4.44.0 to 4.44.3 touches one of the target’s 181 files, although the specification sets no limit on how much a patch may change. ↩︎ Back to text

  2. Swagger Codegen 3.0.84 and 3.0.85 each bundle swagger-codegen-generators 1.0.62, where the templates live, so the two releases carry the same typescript-fetch templates byte for byte. The CLI’s version moved and the templates’ version did not, so the number to record for a template override is the second one. ↩︎ 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.