# How to pick a jostraca file mode for each generated file type

> Give generated code, docs, config and binary assets their own regeneration mode in jostraca, which has a text set and a binary set, and check the backups it leaves.

Source: https://voxgig.com/howto/pick-a-jostraca-file-mode-per-extension

- Audience: library-maintainer
- Level: intermediate
- Languages: typescript, go
- Verified: 2026-11-22
- Published: 2026-11-22

## Short answer

jostraca's existing option has two sets, txt and bin, chosen by whether a file is binary, so it has no key per extension. To give each file type its own mode, map extensions to modes in your generator and run one generate call per mode, each with its own existing. A preserve backup lasts one regeneration, because the next one that changes the file replaces it, so commit before you regenerate and list the .old and .new siblings after.

---
## You will need

Node 22 or later, a jostraca generator that writes at least one file, and an existing generated
output directory. The sample pins jostraca 0.42.0 with its peer `shape`, and the Go half uses the
Go port at the same version. The modes are documented in jostraca's
[options reference](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/reference-options.md#the-order-the-flags-are-checked).

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Copier `_skip_if_exists`](https://copier.readthedocs.io/en/stable/configuring/#skip_if_exists) | A project template, where some files belong to the user after the first copy | One mode per pattern, skip, so a skipped file never gets a later fix | You generate code that changes on every run |
| [Hey API `output.clean`](https://heyapi.dev/docs/openapi/typescript/configuration/output#custom-files) | A TypeScript client in a folder that holds nothing you wrote | One switch for the whole folder: empty it, or keep extra files and overwrite its own | You keep docs or config inside the output folder |
| [jostraca existing file modes](https://jostraca.org/) | You write the generator and can choose a mode for each kind of file | A table of types to keep up, one generate call per mode, and siblings to clean | Nobody edits the output, so the default overwrite is enough |
| [`ogen` `--clean`](https://ogen.dev/docs/intro/) | A Go client in a package where your own files sit beside the generated ones | Its files are always rewritten, and `--clean` deletes by name pattern | You need an edit inside a generated file to survive |
| [OpenAPI Generator `--skip-overwrite` and `.openapi-generator-ignore`](https://openapi-generator.tech/docs/customization/#ignore-file-format) | You generate with it and want some patterns left alone | Ignored files freeze, and no pattern can back up, offer or merge | A file needs the next generate and the edit both |

Voxgig maintains jostraca, the subject of this page, whose repository sits in the `jostraca`
GitHub organization. Voxgig makes none of the other four tools in the table.

The other four decide per folder or per name pattern, and the choice is to write a file or
leave it alone. jostraca offers five modes, and the cost is that someone has to choose one per
type and clean up the files two of them leave. A generator nobody edits gets nothing from that
choice.

## Read the flag order from a run

`modes.mjs` generates one text file and one PNG, edits both by hand, and regenerates under each
setting.

```bash
node modes.mjs
```

```text output
existing                  notes.txt      logo.png      siblings                    files
default                   new generate   new generate  -                           written
txt write:false           edit kept      new generate  -                           written
txt preserve              new generate   new generate  notes.old.txt               preserved written
txt present               new generate   new generate  -                           written
txt present, write:false  edit kept      new generate  notes.new.txt               presented written
txt diff                  diff markers   new generate  -                           conflicted diffed written
txt merge                 merge markers  new generate  -                           conflicted merged written
txt diff and merge        diff markers   new generate  -                           conflicted diffed written
bin preserve              new generate   new generate  logo.old.png                preserved written
bin present, write:false  new generate   edit kept     logo.new.png                presented written
bin diff                  throws: Validation failed for property "bin" with object "{diff:true}" because the property "diff" is not allowed.
```

Three rows matter most. `present` alone changes nothing: it runs only when `write` is false.
`diff` and `merge` together run `diff` alone, and each writes its own markers.[^1] A `txt`
setting never reaches the PNG, and `bin` refuses `diff`, `merge` and `conflict`. The extension
decides which set applies, through jostraca's list of binary extensions, and a NUL byte early
in the file can move an unlisted extension to binary.[^2]

## Map each extension to a mode

The table lives in your generator, because jostraca has no place for it. Each mode is a full
`existing` value, and each extension names one mode.

```js title="policy.mjs"
export const MODES = new Map([
  ['overwrite', { txt: { write: true }, bin: { write: true } }],
  ['offer', { txt: { write: false, present: true }, bin: { write: false, present: true } }],
  ['merge', { txt: { merge: true } }],
  ['backup', { txt: { preserve: true }, bin: { preserve: true } }],
])

export const POLICY = new Map([
  ['.ts', 'overwrite'], // generated code nobody edits
  ['.md', 'offer'], // docs people rewrite: put the new version beside theirs
  ['.json', 'merge'], // config people tune: three-way merge against the last generate
  ['.png', 'backup'], // assets people replace: keep their bytes in a .old sibling
])
```

`modeOf` throws for an extension the table lacks, so an unlisted file type stops the run. It reads
the table as a `Map`, so `constructor` is not a type, and it looks up a name such as `.env` that
has no extension by its whole name.

## Run one generate call per mode

A per-call `existing` is merged key by key over the global one, which a test checks, so each call
gets its own mode and the files keep their own folder.

```js title="policy.mjs"
  const jostraca = Jostraca({ now, log })
  const report = {}
  for (const [mode, group] of groups) {
    const res = await jostraca.generate({ folder, existing: MODES.get(mode) }, () => {
      Project({}, () => {
        for (const file of group) {
          if ('from' in file) Copy({ from: file.from, to: file.path })
          else File({ name: file.path }, () => Content(file.text))
        }
      })
    })
    report[mode] = res.files
  }
```

The PNG goes through `Copy`, which treats it as binary. Each call leaves the other calls' files
in place, as the listings below show for all four.

## Regenerate twice and list the siblings

`twice.mjs` generates version 1.0.0, edits all four files, then generates 1.1.0 and 1.2.0.

```bash
node twice.mjs
```

```text output
after generating 1.1.0
  README.md                   1.0.0 + edit
  README.new.md               1.1.0
  assets/logo.old.png         logo ours
  assets/logo.png             logo 1.1.0
  config/defaults.json        1.1.0 + edit
  src/client.ts               1.1.0
after generating 1.2.0
  README.md                   1.0.0 + edit
  README.new.md               1.2.0
  assets/logo.old.png         logo 1.1.0
  assets/logo.png             logo 1.2.0
  config/defaults.json        1.2.0 + edit
  src/client.ts               1.2.0
```

After the first regeneration every type behaves as its row says. The merge kept the hand-tuned
retry count and took version 1.1.0, and the README kept the edit with the 1.1.0 text beside it.
After the second, `logo.old.png` holds logo 1.1.0: `preserve` backs up whatever is on disk when
it differs from the generate, so the replacement logo from the first edit is gone. A rerun that
changes nothing keeps the backup, as a test shows. Copy a backup out, or commit, before the next
change.

## Keep the siblings out of git

jostraca 0.42.0 only writes the siblings. A test overwrites both with junk and regenerates, and
the junk stays where it is while the generated files come out as before. git lists the siblings
as files it does not track.

```bash
node gitcheck.mjs
```

```text output
git status after regenerating
   M assets/logo.png
   M config/defaults.json
   M src/client.ts
  ?? README.new.md
  ?? assets/logo.old.png
with .gitignore: *.old *.new *.old.* *.new.*
   M assets/logo.png
   M config/defaults.json
   M src/client.ts
  ?? .gitignore
```

The four patterns match the names jostraca makes, which a test checks for `a.old.txt`,
`b.min.old.js`, `noext.old` and `.env.old`. The suffix goes before the last extension, or after
a name that starts with a dot or has no extension. They also hide a real file named
`whats.new.md`, so check your tree with
[`git check-ignore`](https://git-scm.com/docs/git-check-ignore) before you commit them.

## Do the same in Go

The Go port takes the same flags as `*bool` pointers in `jostraca.Existing`, and its
[Go reference](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/reference-go.md) says a
per-call `Existing` in `Options` overlays the global one flag by flag.

```go title="go/main.go"
var yes, no = true, false

var modes = map[string]jostraca.Existing{
	"overwrite": {Txt: jostraca.ExistingTxt{Write: &yes}},
	"offer":     {Txt: jostraca.ExistingTxt{Write: &no, Present: &yes}},
	"backup":    {Txt: jostraca.ExistingTxt{Preserve: &yes}},
}

var policy = map[string]string{".go": "overwrite", ".md": "offer", ".env": "backup"}
```

```bash
go run -C go .
```

```text output
after generating 1.1.0
  .env           1.1.0, generated
  .env.old       1.0.0, hand edit
  README.md      1.0.0, hand edit
  README.new.md  1.1.0, generated
  client.go      1.1.0, generated
refused: no regeneration mode for logo.svg
```

Go's `filepath.Ext` returns `.env` for `.env`, so that file finds its row without the
fallback the TypeScript `modeOf` needs. The Go program has no test of its own: the captured output
is the whole check, and the gate compares it on every run.

## Regenerate without file modes in other generators

Neither generator has a mode per file. Each writes its own files whole and decides only what
happens to the rest of the folder. `record.sh` ran one scenario on both, and on OpenAPI
Generator and Copier:[^3] generate, edit a generated file, add a Markdown file and a hand-written
one, generate again.

```bash
cat records/generators.txt
```

```text output
generate, edit, add files, generate again; what the second run left of each
tool                                setting                   code edit   Markdown    hand-written code
Hey API 0.99.0                      output.clean: true        lost        deleted     deleted
Hey API 0.99.0                      output.clean: false       lost        kept        kept
ogen v1.25.0                        no flag                   lost        kept        kept
ogen v1.25.0                        --clean                   lost        kept        kept
OpenAPI Generator 7.27.0            no flag                   lost        lost        kept
OpenAPI Generator 7.27.0            --skip-overwrite          kept        kept        kept
OpenAPI Generator 7.27.0            ignore file **/*.md       lost        kept        kept
Copier 9.19.1                       _skip_if_exists: *.md     lost        kept        kept
  ogen no flag: oas_stale_gen.go, named like its output: kept
  ogen --clean: oas_stale_gen.go, named like its output: deleted
```

Hey API empties `output.path` before each run unless `clean` is `false`, and its documentation
warns that `false` may leave broken output. The substitute for a mode is a folder: keep the
README and config outside `output.path` and import the client from it. The `--clean` flag of
`ogen` removes only files whose names start with `oas` or `openapi` and end in `_gen.go` or
`_gen_test.go`, as its
[`cleanDir`](https://github.com/ogen-go/ogen/blob/v1.25.0/cmd/ogen/main.go) shows, so your files
in the package are safe by name. An edit inside a generated file is lost under both.

## Check it worked

Sixteen tests run, covering the flag order, sibling names, the per-type run, the second
regeneration, git, and the package glob below.

```bash
node --test modes.test.mjs
```

```text output
1..16
# tests 16
# suites 0
# pass 16
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

The test that carries the page regenerates three times and asserts that `logo.old.png` holds
logo 1.1.0, not the hand-made logo, and that exactly two siblings are on disk.

## When it goes wrong

A fresh clone loses the hand-tuned config. The merge baseline lives in
`.jostraca/generated/`, which jostraca's own `.gitignore` keeps out of git, so the clone has
none and `merge` overwrites the file. Add `conflict: 'fail'` to the merge mode to stop instead,
or set `control.version: true` and commit the baseline.

The README is overwritten although the mode is `offer`. The mode set `present` and left
`write` at its default. Set `write: false` in the same set.

A sibling ships in the package. A glob such as `assets/*.png` in the `files` list of
`package.json` picks up
`logo.old.png` too. Clean the siblings in the build step, or narrow the glob.

## When not to do this

Do not give jostraca a table of modes for output nobody edits. The default overwrite is the
right policy there, and every mode beyond it adds files to ignore and a decision to revisit.

Do not trust `preserve` as a backup. It keeps one generation of history, and the second run in
the test replaced the only copy of the edit. Commit before you regenerate, and let git be
the backup.

Choose Hey API when the client is TypeScript and the output folder holds only generated code:
its emptied folder is a simpler guarantee than any table of modes. Choose `ogen` when your Go
files can sit beside its `oas_*_gen.go` files, because the naming rule does the work a table
does here.

## Related how-tos

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

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

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

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

## Last verified

Verified 2026-11-22 against Node 22.23.5, jostraca 0.42.0 with `shape` 12.2.5, and the Go port
v0.42.0 with Go 1.24.7, and on Go 1.25.0 from an empty module cache. `record.sh` ran `@hey-api/openapi-ts` 0.99.0, `ogen` v1.25.0 on the Go
1.26 toolchain it fetched, OpenAPI Generator 7.27.0 on OpenJDK 21 and Copier 9.19.1, once, and
`records/generators.txt` is what it wrote.

[^1]: jostraca's [options reference](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/reference-options.md)
notes that the generated side of a merge conflict came first before 0.41, and that the
existing side's label carries the previous run's completion time. With no previous run that
time is `-1`, which renders as `1969-12-31T23:59:59.999Z`: a conflict dated one millisecond
before the epoch.

[^2]: The [utilities reference](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/reference-utilities.md)
puts the list at around 250 extensions, from `png` and `pdf` to `woff2` and `docx`, and says
only the last dot segment counts. A basename that starts with a dot has no extension at all,
so `.env` is text by default, and `logo.png.txt` is text too.

[^3]: Copier's own example for
[`_skip_if_exists`](https://copier.readthedocs.io/en/stable/configuring/#skip_if_exists) is a
password the project generates the first time, from a template that hashes a random number,
and should not override after that. The documented use is a secret that must survive every
regeneration, and a README the user rewrote is the same case with lower stakes.