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

Source: https://voxgig.com/howto/move-a-bundled-target-out-of-the-tree

- Audience: library-maintainer
- Level: advanced
- Languages: typescript
- Verified: 2026-11-21
- Published: 2026-11-21

## 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](https://buildwithfern.com/learn/sdks/current/overview/custom-code) | 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](https://openapi-generator.tech/docs/customization/) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/copies-merge.md) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/author-an-sdkgen-package.md) | 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](https://github.com/swagger-api/swagger-codegen/blob/3.0.0/docs/generators.md) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/use-an-sdkgen-package.md)
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 title="acme-sdkgen-ts/local.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](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/migrate-a-bundled-target.md)
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](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/author-an-sdkgen-package.md)
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.

```json title="acme-sdkgen-ts/UPSTREAM.json"
{
  "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:

```bash
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.

```bash
node logs.mjs
```

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

```bash
node upstream.mjs
```

```text output
@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](https://github.com/swagger-api/swagger-codegen/blob/3.0.0/docs/generators.md)
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.

```bash
node swagger.mjs
```

```text output
-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](https://buildwithfern.com/learn/sdks/current/overview/custom-code) 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](https://buildwithfern.com/learn/sdks/current/reference/sdk-config) 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.

```bash
node --test takeover.test.mjs
```

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

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

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

- [Find which template produced a generated file](/howto/find-which-template-produced-a-generated-file)

- [Preview a regeneration as a diff before writing files](/howto/preview-a-regeneration-as-a-diff)

- [Add a Ruby target to an existing multi-language SDK](/howto/add-a-ruby-sdk-target)

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

[^1]: The fix arrived as a patch release, which [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)
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.

[^2]: Swagger Codegen 3.0.84 and 3.0.85 each bundle
[`swagger-codegen-generators` 1.0.62](https://repo1.maven.org/maven2/io/swagger/codegen/v3/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.