How-to › Ship an SDK

How to protect one file from regeneration#

Keep one generated file, such as the README, out of a jostraca regeneration with the JOSTRACA_PROTECT marker, prove it with a hash, and check it on a schedule.

Audience
API producer
Level
beginner
Topic
Regenerate without losing edits
Verified

Your team rewrote the generated README by hand: the real package name, and where to get an API key. The next regeneration writes the template’s README over it, and the release goes out telling users to install the package name the template guessed. A module you patched goes the same way.

What you get

You will end up with one file the generator never rewrites and a hash check that proves it. A scheduled check fails when the generator has changed what that file would have been. This is for you if you own a generated SDK and one of its files has become yours.

Short answer

Put the literal string JOSTRACA_PROTECT anywhere in the file on disk, in an HTML comment for a README, and jostraca 0.42.0 leaves the file’s bytes alone in every existing mode. Regenerate and compare the file’s SHA-256 before and after. The marker freezes the whole file, so generator fixes stop reaching it: compare its merge baseline with a fresh generate on a schedule.

You will need

Node 22 or later and a generated SDK committed to git. The sample is JavaScript: a small generator on jostraca 0.42.0 and shape 12.2.5, which npm ci installs, writes a README and two modules in merge mode. Release 1.1.0 of its templates renames an export and adds a README section.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Fern .fernignoreFern generates the SDK and you own a file end to endListed files stop receiving generator updates, which Fern’s own page names as the trade-offYou want line edits kept, which its Replay merges three ways
Hey APIYour hand code can live in a file Hey API never writesNo per-file protection: an edited generated file is overwritten on every runYou must keep an edit inside a generated file
jostraca JOSTRACA_PROTECT markerYour generator is built on jostraca, sdkgen includedFreezes the whole file, and a list of protected files takes a searchYou want one reviewed list of protected paths
NSwagYour hand code fits in classes the client extendsIt writes one output file, so hand code moves to an extension fileThe edit has to change a generated method body
OpenAPI Generator .openapi-generator-ignoreOpenAPI Generator writes the SDK into one output folderOne list in the output root, and a listed file it would create is never writtenYou move files around and want protection to follow them
Speakeasy .genignoreSpeakeasy generates the SDK and the file is docs or examplesSpeakeasy warns that ignored files break when generator changes rename symbolsIts custom code feature can keep the edit with a merge

Voxgig maintains jostraca, the subject of this page, and sdkgen writes its files through it. The other five rows are other projects’ tools.

An ignore file lists every protected path in one reviewed place, and can stop a file from ever being written. The marker travels with the file, but you find protected files only by searching for the string. Hey API and NSwag have neither, so hand code goes in a file they never write.

Protect the README and regenerate

jostraca reads the file already on disk and checks it for the substring in FileHandler.ts at v0.42.0, before any mode runs. The generated content is never checked. protect.mjs adds the marker in an HTML comment, which a Markdown renderer hides:

export const MARKER_LINE = '<!-- JOSTRACA_PROTECT: this README is written by hand -->\n'

It generates 1.0.0, rewrites the install steps, hashes the README, generates 1.1.0, and hashes it again. Then it takes the marker out and generates 1.1.0 once more:

node protect.mjs
generate 1.0.0                     {"written":["README.md","src/client.js","src/retry.js"]}
generate 1.1.0, README protected   {"merged":["src/client.js","src/retry.js"]}
generate 1.1.0, marker removed     {"merged":["README.md"],"unchanged":["src/client.js","src/retry.js"]}
README.md sha256 before 1.1.0: 57219e9492ab4d37
README.md sha256 after 1.1.0:  57219e9492ab4d37  unchanged
src/client.js after 1.1.0:     VERSION 1.1.0
README.md after the marker came out:
  | # Print SDK
  | 
  | Release 1.1.0.
  | 
  | ## Retries
  | 
  | Every call is retried up to 4 times.
  | 
  | ## Install
  | 
  | npm install @printshop/sdk
  | 
  | Ask the platform team for an API key.

The protected README appears in no file list, and its hash did not move while both modules went to 1.1.0. Once the marker came out, the merge ran against the baseline in .jostraca/generated/, which still held the 1.0.0 README. So the release line and the Retries section landed, and the hand edit stayed.

Check every mode

The reference says the marker skips every mode except one. modes.mjs protects the README, then regenerates under each existing setting. How each mode treats a file with no marker is the subject of picking a jostraca file mode for each generated file type:

node modes.mjs
existing                 README.md  listed in   beside it
write (the default)      kept       none        nothing
merge                    kept       none        nothing
diff                     kept       none        nothing
preserve                 kept       none        nothing
write: false, present    kept       presented   README.new.md
write: true, present     kept       presented   README.new.md
the same edit without the marker, write: true, present: README.md overwritten, listed in written, beside it nothing

The bytes survive every mode. present still writes README.new.md beside a protected file, which the reference documents for write: false. Its order of checks says “present does nothing unless write: false” for every file. The run disagrees for a protected file: write: true with present wrote the sibling too, and left an unmarked file with none. Line 461 of FileHandler.ts decides it, since existing.write && !protect is false for a protected file, so the present branch runs.

Check it worked

Hash the file before and after a regeneration in CI. The suite does that, and checks each claim on this page, the clone and the scheduled check included:

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

Keep a file in Hey API and NSwag

record.sh ran both generators on api.json with a hand edit in place. others.mjs prints what it recorded, with OpenAPI Generator’s ignore file for comparison:

node others.mjs
records/hey-api.txt
  clean: true
    sdk.gen.ts hand edit kept: no
    retry.ts, a file it does not write, kept: no
  clean: false
    sdk.gen.ts hand edit kept: no
    retry.ts, a file it does not write, kept: yes
records/nswag.txt
  nswag NSwag version: 14.8.0.0
    openapi2tsclient help lists: ClientBaseClass,ExtensionCode
    extension.ts sha256 before: 6ad458db2ded6cce, after two runs: 6ad458db2ded6cce
    client.ts holds the extension class: yes
    client.ts hand edit kept: no
    tsc 5.9.3 --strict on client.ts: exit 0
records/openapi-generator.txt
  openapi-generator 7.27.0
    README.md written with no ignore file: yes
    README.md written by the first run with it ignored: no
    README.md sha256 before the second run: 67dea8c10f4341ee, after: 67dea8c10f4341ee
    src/runtime.ts hand edit kept: no

Hey API has no way to protect a file it generates. Its output page says custom files cannot stay in the output folder, because it is emptied on every run, unless clean is false. record.sh searched the 71 TypeScript pages its llms.txt lists for custom files, ignore file, protect and preserve, and of the six that matched, only that page is about keeping a file. With clean: false, a file of your own survived and the edited sdk.gen.ts did not.

NSwag writes one file per run, so an edit to client.ts is lost. Its TypeScript client settings take ExtensionCode, a file of your own that NSwag copies into the client. The wiki calls the base class setting BaseClass, and the command line lists it as ClientBaseClass, which names a class in that file. Both runs left nswag/extension.ts unchanged, and the client passed tsc --strict.

OpenAPI Generator’s typescript-fetch writes a README only when npmName is set, so record.sh sets it. A control run without the ignore file wrote README.md, and the run that listed it did not.

When it goes wrong

The client stops loading after a regeneration. The protected module kept its 1.0.0 export while the generated client moved on, as Speakeasy’s code regions page warns of ignored files. pitfall.mjs protects src/retry.js, and release 1.1.0 renames its export:

node pitfall.mjs
generate 1.1.0, src/retry.js protected: {"merged":["README.md","src/client.js"]}
import src/client.js: SyntaxError: The requested module './retry.js' does not provide an export named 'withRetry'
the scheduled check, stale.mjs, on the same tree:
src/retry.js: behind
  - export const ATTEMPTS = 3
  + export const ATTEMPTS = 4
  - export async function retry(fn) {
  + export async function withRetry(fn) {
exit status: 1

Run node stale.mjs <folder> <release> on a schedule. It compares each protected file’s baseline with a fresh generate in memory, and exits 1 on any difference, a missing baseline, or a tree in which no file holds the marker.

The hand edit vanishes when the marker comes out in a fresh clone. The baseline sits in .jostraca/generated/, which jostraca’s own .gitignore drops, as regenerating an SDK with a three-way merge sets out for every merged file:

node clone.mjs
default control       baseline in clone: no   README.md unmerged, written  hand edit lost, Release 1.1.0
control.version true  baseline in clone: yes  README.md merged  hand edit kept, Release 1.1.0

Set control: { version: true } and commit .jostraca/ before you rely on removing a marker.

Protection ends when the file does. edges.mjs shows a deleted protected file written again without the marker, and markers around one section freezing the whole file. A lowercase marker protects nothing, and a template that prints the string protects its own output from the second run on.1

When not to do this

Do not protect a file to keep an edit you could move. A hand-written module beside the generated ones, which jostraca never writes, needs no marker, and the generator’s fixes keep landing in the files it owns.

Skip the marker when the protected set must be reviewed in one place. An ignore file in OpenAPI Generator, Speakeasy or Fern is that list, and the jostraca marker is not.

Do not move to jostraca for one file. If Hey API writes your SDK, keep the hand code outside its output folder, or set clean: false. If NSwag does, extension code survives every run and type checks with the client. Both are a smaller change than adopting another generator.

Last verified

Verified 2026-11-22 against Node 22.23.5, jostraca 0.42.0, the newest on npm, and shape 12.2.5. Hey API 0.99.0, NSwag 14.8.0 and OpenAPI Generator 7.27.0 ran once in record.sh, and the page reads what it recorded, with .NET’s telemetry opt-out set for NSwag. Fern and Speakeasy were not run, and their rows come from their documentation.

Footnotes

  1. The check is currentContent.indexOf(JOSTRACA_PROTECT) on the bytes already on disk, so JOSTRACA_PROTECTED protects a file and jostraca_protect does not. The reference describes the marker as “Not a line, not a comment, not anchored” before it calls it a substring. A generated page that explains the marker therefore protects itself from its second run on. ↩︎ 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.