Why A Generator Built for the Second Run Makes Sense

First impressions

At first, I understood little of what Jostraca does.

The first line, "Regenerate a file tree after manual edits," may raise the question, "Why would someone do that?". Because that's not the normal workflow.

Scaffold?
The examples of scaffolds or starter templates may sound more common and understandable -
"create-next-app" simply creates a Next.js starter app that you can begin customizing. But after you have made edits, there is almost never a need to re-generate the app (by deleting the project and generating it again, or by generating a fresh copy elsewhere).
But that is not what Jostraca does.
It is not related to commands that spin up a starter project with templates you are meant to edit and never touch the generation command again.

Layer?
After reading a bit, I started to think "Is it a layer over existing generators?". Consider generators like Prisma Generator: you write the specifications, run the generator, and now have the artifacts needed for your project and can use them.
If Jostraca is a layer between the existing generator and its generated output, you could edit that output and still preserve those edits when regenerating artifacts after specification changes.
And the answer is "NO". Jostraca is not a layer that sits on top of existing generators such as Prisma Generator.

Generator Framework
Like how Nextjs is a framework for creating websites, Jostraca is a framework for creating generators.

The homepage might seem a bit ambiguous and not easily understandable but complete the tutorial at https://jostraca.org/docs/tutorial/ (or https://github.com/jostraca/jostraca/blob/main/docs/tutorial.md) and you will have most of the information about how to work with Jostraca.

Where Jostraca finds its place

Jostraca finds its place among developers who are building generators.
Generators like:

• SDK generators that need to be regenerated when APIs change.
• Internal company templates that evolve over time.
• Boilerplate systems shared across multiple teams.
• Code generators where developers are expected to customize generated output.

Any system or product where regeneration should not erase hours of work is a potential use case for Jostraca.

Where Jostraca does not find its place

Jostraca does not find its place in one-time scaffolding tools, starter templates, or generators whose output is never expected to be regenerated. If the generation is meant to run only once, then Jostraca has little benefit.
For these cases, a simpler scaffolding approach is both - sufficient and efficient.

Following the tutorial

Following the tutorial will give you the knowledge needed to use Jostraca effectively - as the generator framework it is meant to be.
Although you might not understand everything in the tutorial immediately, as you progress in the tutorial, much of it will make sense.

Coding Example

To explore Jostraca beyond the tutorial, I built a small Math Toolkit Generator. The generator takes a simple configuration object (project name, version, functions, and feature flags) and produces a small project containing JavaScript functions, documentation, configuration files, and a basic HTML interface.

Coding example at Github: https://github.com/ShivRaiGithub/Jostraca-math-toolkit

The goal was to observe how different files and different modes behave when the generator is run a second time after a developer has modified them.

The project contains several file types, each using a different regeneration strategy:

• basicFunctions.js is fully generated from configuration. If a new function such as power() is added to the config, the file is completely regenerated. This makes sense because it is pure generated code and should always reflect the latest configuration.
• customFunctions.js contains user-owned code and a generated section. On regeneration, only the generated block is updated while user-written functions remain untouched. This allows developers to extend the project safely.
• userNotes.md is protected using JOSTRACA_PROTECT. Since notes are entirely user-owned content, the generator never modifies the file after creation.
• README.md and package.json are regenerated every run because they are derived entirely from the current configuration and should stay synchronized.
• index.html uses Jostraca's merge functionality. Generated UI elements, such as operation buttons, can be updated while preserving user customizations like additional styling or custom sections.
• latest-updates.txt demonstrates preservation. When regenerated, the previous version is stored as a backup, allowing the history of generated output to be retained.
• config-summary.json demonstrates diff mode. Instead of automatically replacing content, Jostraca writes explicit EXISTING and GENERATED blocks so changes can be reviewed before being accepted.

There are two scripts, run and run2, in package.json that execute the generator using two different configuration files. Running the generator clearly demonstrated how each regeneration strategy behaves and, more importantly, why different files often require different update policies.

Observations after working with Jostraca

The Complexity in theory

You might think you understand what Jostraca does at first, but questions start to arise once you think more deeply about it. The complexity is not in using Jostraca. It's in understanding what problem it solves. Most developers are familiar with one-time scaffolding tools, but not with tools designed for regeneration.

The Simplicity in working

You only need a single package, jostraca (installable via npm install jostraca), to get started.
Even simple generators can be created by executing a single file containing Jostraca code.

Although understanding the problem Jostraca solves may take some time, getting a basic generator running requires surprisingly little code.

The 5 modes

Jostraca provides five modes that determine what happens to an already-generated file. The 5 modes being write, preserve, present, diff,merge - each enabling a specific action to be taken. This allows different files in a generated project to follow different regeneration policies rather than treating every file the same way.

My favorite part

The feature I found most interesting in Jostraca was "JOSTRACA_PROTECT".
This essentially provides a very strong option for the user to safeguard any generated file and prevent any further edits by the generator.
Any file containing this string is protected from modifications triggered by regeneration.

A point to note

One behavior that surprised me was template path resolution. When using Fragment with an HTML template, the from path is resolved relative to the output folder, not the generator script itself. This meant I had to reference the template from the perspective of ./out, which felt unusual at first.

Final Verdict

Jostraca is not a tool for every developer, and it does not try to be. Most application developers will never need regeneration-aware code generation. However, for developers building generators, SDK tooling, or long-lived templates, Jostraca provides a practical set of mechanisms for handling generated files after users start modifying them.