How-to › Ship an SDK

How to vendor a generated SDK into your repo and take upgrades#

Vendor an SDK Catalog TypeScript SDK with `git subtree` or a patch series, keep two local patches across one regeneration, or wrap the Go module.

Audience
API consumer
Level
advanced
Topic
Regenerate without losing edits
Verified

You copied a generated SDK into your monorepo and patched two files so it sends your headers. The upstream repository regenerates the SDK, and the regeneration rewrites both files. The next upgrade either drops your patches or stops on conflicts in code nobody on your team wrote.

What you get

You will end up with a vendored SDK, two local patches, and one upstream regeneration taken through git subtree and through a patch series, with the SDK checked after each. This is for you if you depend on a generated SDK whose maintainers owe you no fix.

Short answer

Vendor the generated SDK with git subtree add --squash, commit each local change as its own patch, and pull a regeneration with git subtree pull --squash, or keep the patches as a series and reapply them with git am --3way. Resolve each conflict by taking the regenerated file and making the edit again. Where the SDK takes the change as an option, pass it instead and skip the patch.

You will need

git with git subtree, which ships with git on Ubuntu, and Node 22 or later. The upstream is the TypeScript SDK in voxgig-sdk/jsonplaceholder-sdk, whose README calls it unofficial and “not affiliated with” the API it wraps. The sample’s upstream.bundle holds its compiled files at two regenerations, so every command runs offline.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
git format-patch and git am patch seriesYou want the vendored tree to stay exactly upstream plus a list of named changesEach upgrade replays every patch, and a regenerated file stops git am on itYour patches are few and history in one place suits you
git subtreeYou want the upstream inside your repository with no extra tooling for clonesEvery pull is a merge you resolve, and the --squash choice must never changeYou can take the change as an option and vendor nothing
KiotaYou generate the client yourself and add behavior through middlewareIts client is yours to regenerate and commit, with its runtime packages to keep currentYou consume someone else’s SDK as it ships
oapi-codegenA Go client you generate, with headers set by a RequestEditorFnOne generated file per run, regenerated by you, and its runtime raised go.mod to Go 1.26The SDK comes from another team’s repository
SDK Catalog repo as upstreamAn SDK for a public API that its provider does not publishRegenerations land as untagged commits, and nobody upstream answers for a bugThe API’s provider publishes a supported SDK
wrapper around the published packageThe package is published and takes your change as an optionA bug stays unfixed until upstream ships, and only Go is published hereYou must change behavior that no option reaches

Voxgig maintains the SDK Catalog and the generator behind it. It is one of six options here, not the recommendation.

A vendored copy buys offline builds and full control, and each regeneration then becomes your merge. Wrapping keeps an upgrade to a version bump, at the price of waiting on upstream for a fix. Kiota and oapi-codegen sit on the other side: a team that generates its own client never vendors it, and puts its additions in code the generator never writes.

Vendor the earlier regeneration and patch it

The catalog’s regenerations land on main without a tag. The repository’s newest TypeScript tag predates both commits used here.

node records.mjs
the catalog repository
  main: a21ce5a97d8ed4c85e02123b61a67a3a408d60a9
  old:  317cc9dcf13787659643517b15d436d47cc8952e 2026-10-01 Regenerate on sdkgen 4.33.0 and apidef 8.22.1
  new:  a21ce5a97d8ed4c85e02123b61a67a3a408d60a9 2026-11-03 Regenerate on sdkgen 4.38.0 and apidef 8.27.0
  newest ts/ tag: ts/v0.0.7 2026-08-13
  commits to ts/ after that tag: 12
  npm view @voxgig-sdk/jsonplaceholder-sdk: exit 1
the published Go module, wrapped
  go.mod: github.com/voxgig-sdk/jsonplaceholder-sdk/go v0.0.8-0.20261001173714-317cc9dcf137 // indirect
  load post 1: title=Lamp keys=[body id title userId]
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
  go.mod: github.com/voxgig-sdk/jsonplaceholder-sdk/go v0.0.8-0.20261103055737-a21ce5a97d8e
  load post 1: title=Lamp keys=[body id title userId]
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
  go1.24.7
oapi-codegen
  oapi-codegen v2.8.2, 277 lines in client/posts.gen.go
  go.mod: go 1.26.0
  load post 1: status=200 title=Lamp
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"

Pin a commit, not a tag. The TypeScript package, @voxgig-sdk/jsonplaceholder-sdk in its package.json, is not on npm, so a TypeScript team has no package to wrap and vendors the source.

Add the upstream with git subtree add --prefix=vendor/jsonplaceholder <upstream> regen-old --squash. Then apply the two local changes as patches. The first sets your User-Agent right before the SDK calls fetch:

diff --git a/vendor/jsonplaceholder/dist/utility/FetcherUtility.js b/vendor/jsonplaceholder/dist/utility/FetcherUtility.js
index 57f5771..cf14ffd 100644
--- a/vendor/jsonplaceholder/dist/utility/FetcherUtility.js
+++ b/vendor/jsonplaceholder/dist/utility/FetcherUtility.js
@@ -14,6 +14,8 @@ async function fetcher(ctx, fullurl, fetchdef) {
             ' (URL was: "' + fullurl + '")');
     }
     const fetch = options.system.fetch;
+    // LOCAL PATCH: identify this service to the API.
+    fetchdef.headers = Object.assign({}, fetchdef.headers, { 'user-agent': 'shop-billing/1.0' });
     const response = await fetch(fullurl, fetchdef);
     return response;
 }

The second adds an x-request-source header in PrepareHeadersUtility.js. The patches are compiled JavaScript, because the vendored tree is what Node loads.

Pull one regeneration through each route

Pull the later regeneration both ways, resolve, and check what the vendored SDK sends.

node upgrade.mjs
git subtree, --squash on add and on pull
  pull: exit 1, conflicts in dist/utility/FetcherUtility.js, dist/utility/PrepareHeadersUtility.js
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
git subtree, --squash on add, none on pull
  pull: exit 128, fatal: refusing to merge unrelated histories
git subtree, no --squash on add, --squash on pull
  pull: exit 1, conflicts in dist/utility/FetcherUtility.js, dist/utility/PrepareHeadersUtility.js
patch series, git am --3way on the new regeneration
  git am on the old: exit 0; on the new: exit 128, conflicts in dist/utility/FetcherUtility.js, dist/utility/PrepareHeadersUtility.js; refreshed 2 patches
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
no patch, regen-old as released
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent=null x-request-source=null
no patch, regen-old, with the headers passed as an SDK option
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
no patch, regen-new as released
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent="Mozilla/5.0 (compatible; JsonplaceholderSDK/1.0)" x-request-source=null
no patch, regen-new, with the headers passed as an SDK option
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"

Both routes stopped on the same two files. The regeneration rewrote the lines around each patch: it added a guard and a default User-Agent between const fetch and the call, and cookie handling before return out. Each conflict is resolved the same way, by taking the regenerated file and making the edit again with patch-edits.mjs, which refuses a file that already holds the edit.

The series route then refreshes the patches with git format-patch, so the next upgrade starts from patches written against this regeneration. Both routes end with the same tree.

The last four runs carry the finding that matters most. Upstream’s headers option sends both headers on both regenerations with no patch at all. It does not carry every header: an authorization header passed the same way never reached the stand-in, which the test also asserts. Read the SDK’s options before you patch it.

Check it worked

The test rebuilds each route in a scratch repository. It asserts the conflicts, the headers the stand-in received, and the offline test mode. It also checks that the resolved tree differs from the regeneration in the two patched files only.

node --test vendor.test.mjs
1..8
# tests 8
# suites 0
# pass 8
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 3375.500747

The catalog’s own test suite is TypeScript and rebuilds dist/ from src/ before it runs, which would overwrite a patch made to the compiled files. The sample therefore checks the vendored build with its own test and the SDK’s offline test mode.

Add the same headers with oapi-codegen and Kiota

A team on oapi-codegen generates its own Go client and commits the one file it writes. The headers go in a RequestEditorFn in the team’s code, so a regeneration rewrites the file without touching them. record.sh ran it once against the stand-in, as the catalog record earlier shows.

func shopHeaders(_ context.Context, req *http.Request) error {
	req.Header.Set("User-Agent", "shop-billing/1.0")
	req.Header.Set("X-Request-Source", "shop-billing")
	return nil
}

Kiota puts the same change in a middleware handler that you register when you build the HTTP client, as its middleware page shows for TypeScript, C#, and Python. That page lists a default User Agent handler that adds the Kiota HTTP library version to the header. Kiota was not run here, so this paragraph rests on that page alone.

The Go wrapper takes the same route through the catalog SDK’s own options, and its upgrade was one go get of a pseudo-version.

// NewShopClient is the whole wrapper.
func NewShopClient(base string) *sdk.JsonplaceholderSDK {
	return sdk.NewJsonplaceholderSDK(map[string]any{
		"base": base,
		"headers": map[string]any{
			"user-agent":       "shop-billing/1.0",
			"x-request-source": "shop-billing",
		},
	})
}

When it goes wrong

git subtree pull fails with refusing to merge unrelated histories. The add used --squash and the pull did not, so git sees two histories with no common commit. Pull with the same --squash choice the add used, every time.1

git am --3way stops on a patch. The regeneration changed the lines around it. Take the regenerated file with git checkout --ours, make the edit again, git add it, and run git am --continue. In a git subtree merge, the regenerated side is --theirs.

The User-Agent changes after an upgrade without a conflict. The regeneration added a default agent, so an SDK you never patched starts sending Mozilla/5.0 (compatible; JsonplaceholderSDK/1.0).

When not to do this

Do not vendor to change a setting the SDK already takes. The catalog SDK’s headers option did the work of both patches on both regenerations.

Do not vendor a catalog SDK expecting upstream to fix a bug for you. The README disclaims affiliation with the API, and the repository regenerates on its own schedule. A vendored copy makes that schedule your merge queue.

Choose oapi-codegen when you can generate the Go client yourself from the provider’s document: its editors keep your headers out of the generated file. Choose Kiota for the same reason in C#, TypeScript or Python, the languages its middleware page shows, with middleware in place of editors. Wrap the published Go module when you can, since its upgrade is a version bump.

This page vendored no SDK that the API’s own provider publishes and supports, such as one its provider generates with Speakeasy or Fern, so it holds no record of that case. There, a bug report goes to the team that ships the SDK, which makes wrapping its package the first route to try.

Last verified

Verified 2026-11-22 against Node 22.23.5 and git 2.43.0, on the catalog commits 317cc9d and a21ce5a. The Go wrapper and oapi-codegen v2.8.2 ran once, in record.sh, against a stand-in, and their output is committed. Kiota was read from its documentation and not run.

Footnotes

  1. The git-subtree documentation says --squash makes “a single commit that contains all the differences you want to merge”. With it, the page adds, you can “switch back and forth between different versions” rather than only move forward. It says nothing about a pull that drops the flag. In the sample, a pull without it after a squashed add stopped with refusing to merge unrelated histories, and the reverse pairing reached the same two content conflicts as a matched pull. ↩︎ 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.