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.
Choose an existing-file mode before regenerating files that contain manual edits. The explanation describes the two phases and the cost of keeping a merge baseline.
Components use ordinary function calls for iteration and branching. Template markers can sit in the target language’s comment syntax, leaving the file valid source. See template markers.
Two implementations, held together
Jostraca ships as a TypeScript package on npm and as a Go module. TypeScript defines the contract. Correct any TypeScript defect first, then bring Go into parity. 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.36.6, 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. An imported page can describe changes ahead of the installed release. /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.