About
Jostraca is an open source code and project generator. It is a library you import, not a service you call, and this site is its documentation.
What it is
Jostraca builds file trees from components. You declare Project,
Folder, File and Content inside a callback;
that callback touches nothing on disk, it records an in-memory tree. A second
phase then walks the tree and writes it. Because the whole intended output is
known before the first byte is written, a second run over code somebody edited
by hand has choices—preserve it, present the new version beside it, write a
diff, or perform a three-way merge—instead of one destructive default.
That is the entire reason the project exists. Most generators are delightful once and dangerous twice; the cost of making the second run safe is the two-phase design, and the explanation argues it in full, including what it costs.
There is no template language in any of this. Components are function calls, so iteration and branching are the ones your language already has. Where Jostraca does read a template file, the marker sits inside the target language’s own comment syntax, which leaves the file valid HTML, or Go, or SQL — and leaves your editor, formatter, and linter with nothing new to learn. Why that matters.
Two implementations, held together
Jostraca ships as a TypeScript package on npm and as a Go module. TypeScript is canonical: when the two disagree, Go is the one that changes, even on the occasions when the Go code happens to be more correct. The two are held to the same behaviour by a shared, language-neutral test corpus that both stacks assert against, so a divergence fails a test rather than surprising somebody a release later.
Two versions matter here, and they are not always the same one. This site
runs its own authored examples against 0.33.1, the
package it pins. The documentation pages are synced from the generator's
repository, where each snippet is executed in a temporary directory by a
Node.js process and compared against the file tree it wrote, using the code
at that commit, which can be ahead of the published package. So a synced
page cannot drift from the generator, but it can describe a release you have
not installed yet. /versions.json reports the
pin, and each page links the file it came from.
Who maintains it
Jostraca is written and maintained by Richard Rodger, who has been building and writing about component-oriented systems in Node.js for a long time. The project is MIT licensed. Contributions, bug reports, and corrections are welcome through the issue tracker; see contact.
Where everything lives
- The generator
- Both implementations, the shared corpus, and the documentation these pages are generated from.
- This site
- The Astro source for jostraca.org. Versioned and deployed separately from the generator.
- /llms.txt and /openapi.json
- The machine-readable index and the description of this site's content API, for agents and tooling. Every page here is also served as markdown.
Next: the tutorial builds a generator from nothing, and why Jostraca makes the case for the design.