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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Fern .fernignore and Replay | Fern generates the SDK and the change is to its output | Edits land in output files, and the generator itself is not yours to change | You need the change in every SDK the generator writes |
| OpenAPI Generator language class fork | Templates cannot reach the change, and a Java build is acceptable | A Java module to build, and every upstream change to the class to port by hand | One template override would carry the change |
| sdkgen bundled target with its copy edited | One project needs the change | Each project carries its own edit, merged again on every generator update | Several projects need the same change |
| sdkgen target in a package of your own | Several projects need one changed target | Every upstream fix to that target reaches you only when you port it | One project, or a change one copy edit carries |
| Swagger Codegen custom templates | Swagger Codegen generates the SDK and a template holds the change | A template directory to diff against each release’s bundled templates | The 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.
Related how-tos
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
-
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
-
Swagger Codegen 3.0.84 and 3.0.85 each bundle
swagger-codegen-generators1.0.62, where the templates live, so the two releases carry the sametypescript-fetchtemplates 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