Jostraca documentation

Rendered from docs/index.md in the generator repository — where a correction belongs, and where the test suite runs every example on this page or states why it does not.

Jostraca is a code and project generator. You describe an output file tree with components—Project, Folder, File, Content and the rest—inside a callback, and Jostraca writes the tree to disk. The callback runs first and touches nothing: it records an in-memory node tree. Only then does the build phase write files. That split is why a second run over code somebody has edited by hand has choices rather than a single destructive default.

There is no template syntax to learn. You write code, in the language you are already in: iteration is for, branching is if, reuse is a function. Where a file reads better as a file, you keep it as one and mark the regions to fill—and the marker is allowed to sit inside that language’s own comment syntax, so the template is still valid HTML, or Go, or SQL. It opens, highlights, formats, and lints like any other file of its type. No file that is valid in neither language, and no editor that needs a plugin to read it. See no template syntax to learn.

This repository ships two implementations kept in parity:

• TypeScript in ts/, the canonical implementation, published to npm as jostraca.
• Go in go/. A port (github.com/jostraca/jostraca/go) that aims at byte-identical output for the same logical input.

Both are checked against one language-neutral corpus in test/spec/, and every example in these pages is executed by ts/test/docs.test.ts: each snippet runs in a temp directory and the pages state the tree it actually wrote.

How this documentation is organised#

The documentation is split by what you are trying to do when you open it. Reach for the part that matches your need:

The how-to guides are one page per task, grouped six ways: composing the output tree; templates and fragments; reusable components; regenerating over existing files; files, copying and permissions; and embedding Jostraca in your own tool.

The parts, in one place#

The components. Project roots a generated tree, Folder and File build the path, Content and Line put text in a file. Fragment reads a template file from disk and Slot fills the marked regions inside it. Copy brings in a file or a whole directory, templating text on the way through. Inject edits between markers in a file that already exists. List emits one block per array item. Anything else is a function you write and wrap with cmp(). Each is specified in the component reference.

The model and the template syntax. Pass a model to Jostraca() and $$path$$ inside content substitutes the value at that path. The syntax has no conditionals, loops or expressions, and that is the whole design: the surrounding code is a programming language already. The utilities reference documents template() and the replace map for the cases the plain form cannot reach.

The existing-file modes. write overwrites, preserve keeps the old bytes in a sibling file, present writes the new version beside an untouched original (it needs write: false, which is checked first), diff writes an annotated two-way diff, and merge performs a three-way merge against the previous generate. A file containing JOSTRACA_PROTECT is never overwritten under any of them. The options reference specifies each; the regenerating guides show them in use.

In-memory generation. mem: true runs the whole thing on a virtual filesystem, which is how you test a generator without a temp directory. See generate in memory.

For contributors#

TypeScript is the source of truth. A behaviour change lands in ts/src/ first and Go follows it; make all from the repository root builds and tests both stacks.

• The style guide. How these pages are written: which kind of page a fact belongs on, the voice, the banned-phrase list, and the snippet directives under which every example runs.
• test/spec/. The shared corpus. A change to any pure helper adds a row there rather than a case in one stack’s suite.

If a page here is wrong, it is wrong in this repository. Fix it here; jostraca.org renders these files rather than holding a second copy of them.