How-to › Ship an SDK

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.

Audience
Library maintainer
Level
intermediate
Topic
Regenerate without losing edits
Languages
TypeScript and Go
Verified

Your generator writes TypeScript, Markdown, JSON and PNG files into one folder, and people edit some of them. Under jostraca’s default, a regeneration overwrites all four, so a tuned retry count and a rewritten README go with the code nobody touched. Turning preserve on for everything instead leaves a backup beside every generated source file.

What you get

You will end up with a table from extension to mode, one generate call per mode, and a test that regenerates twice and lists the siblings left behind. This is for you if your generator writes several kinds of file and people edit some kinds and not others.

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.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Copier _skip_if_existsA project template, where some files belong to the user after the first copyOne mode per pattern, skip, so a skipped file never gets a later fixYou generate code that changes on every run
Hey API output.cleanA TypeScript client in a folder that holds nothing you wroteOne switch for the whole folder: empty it, or keep extra files and overwrite its ownYou keep docs or config inside the output folder
jostraca existing file modesYou write the generator and can choose a mode for each kind of fileA table of types to keep up, one generate call per mode, and siblings to cleanNobody edits the output, so the default overwrite is enough
ogen --cleanA Go client in a package where your own files sit beside the generated onesIts files are always rewritten, and --clean deletes by name patternYou need an edit inside a generated file to survive
OpenAPI Generator --skip-overwrite and .openapi-generator-ignoreYou generate with it and want some patterns left aloneIgnored files freeze, and no pattern can back up, offer or mergeA 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.

node modes.mjs
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.

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.

  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.

node twice.mjs
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.

node gitcheck.mjs
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 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 says a per-call Existing in Options overlays the global one flag by flag.

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"}
go run -C go .
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.

cat records/generators.txt
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 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.

node --test modes.test.mjs
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.

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.

Footnotes

  1. jostraca’s options reference 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. ↩︎ Back to text

  2. The utilities reference 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. ↩︎ Back to text

  3. Copier’s own example for _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. ↩︎ 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.