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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
Fern .fernignore | Fern generates the SDK and you own a file end to end | Listed files stop receiving generator updates, which Fern’s own page names as the trade-off | You want line edits kept, which its Replay merges three ways |
| Hey API | Your hand code can live in a file Hey API never writes | No per-file protection: an edited generated file is overwritten on every run | You must keep an edit inside a generated file |
jostraca JOSTRACA_PROTECT marker | Your generator is built on jostraca, sdkgen included | Freezes the whole file, and a list of protected files takes a search | You want one reviewed list of protected paths |
| NSwag | Your hand code fits in classes the client extends | It writes one output file, so hand code moves to an extension file | The edit has to change a generated method body |
OpenAPI Generator .openapi-generator-ignore | OpenAPI Generator writes the SDK into one output folder | One list in the output root, and a listed file it would create is never written | You move files around and want protection to follow them |
Speakeasy .genignore | Speakeasy generates the SDK and the file is docs or examples | Speakeasy warns that ignored files break when generator changes rename symbols | Its 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.
Related how-tos
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
-
The check is
currentContent.indexOf(JOSTRACA_PROTECT)on the bytes already on disk, soJOSTRACA_PROTECTEDprotects a file andjostraca_protectdoes 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