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

Source: https://voxgig.com/howto/protect-one-file-from-regeneration

- Audience: api-producer
- Level: beginner
- Verified: 2026-11-22
- Published: 2026-11-22

## 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`](https://buildwithfern.com/learn/sdks/current/overview/custom-code) | 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](https://heyapi.dev/docs/openapi/typescript/configuration/output) | 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](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/reference-options.md#jostraca_protect) | 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](https://github.com/RicoSuter/NSwag/wiki/TypeScriptClientGenerator) | 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`](https://openapi-generator.tech/docs/customization/#ignore-file-format) | 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`](https://www.speakeasy.com/docs/sdks/customize/code/custom-code/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`](https://github.com/jostraca/jostraca/blob/v0.42.0/ts/src/build/FileHandler.ts#L430)
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:

```js title="protect.mjs"
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:

```bash
node protect.mjs
```

```text output
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](/howto/pick-a-jostraca-file-mode-per-extension):

```bash
node modes.mjs
```

```text output
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](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/reference-options.md#the-order-the-flags-are-checked)
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`](https://github.com/jostraca/jostraca/blob/v0.42.0/ts/src/build/FileHandler.ts#L461)
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:

```bash
node --test protect.test.mjs
```

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

```bash
node others.mjs
```

```text output
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](https://heyapi.dev/docs/openapi/typescript/configuration/output) 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](https://github.com/RicoSuter/NSwag/wiki/TypeScriptClientGenerator)
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](https://www.speakeasy.com/docs/sdks/customize/code/code-regions/overview) warns
of ignored files. `pitfall.mjs` protects `src/retry.js`, and release 1.1.0 renames its export:

```bash
node pitfall.mjs
```

```text output
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](/howto/regenerate-sdk-with-three-way-merge) sets out
for every merged file:

```bash
node clone.mjs
```

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

- [Regenerate an SDK with a three-way merge and keep edits](/howto/regenerate-sdk-with-three-way-merge)

- [Pick a jostraca file mode for each generated file type](/howto/pick-a-jostraca-file-mode-per-extension)

- [Set an overwrite policy for a regenerated SDK](/howto/set-an-overwrite-policy-for-regeneration)

- [Keep generated files out of a coding agent's edits](/howto/keep-generated-files-out-of-agent-edits)

- [Keep Cursor rules and CLAUDE.md in sync from one source](/howto/keep-cursor-rules-and-claude-md-in-sync)

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

[^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](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/reference-options.md#jostraca_protect)
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.