# Jostraca > Jostraca builds file trees from components. You declare Project, Folder, File and Content in a define phase; a build phase writes the result. Because the whole intended output is known before a byte is written, a second run can preserve, present, diff or merge against the code a human edited in between. This site runs its own executed examples against `jostraca` 0.33.1. The pages below are synced from the generator repository and may describe a later release; each one links the file it came from. Every page is also served as markdown: append `.md`, or send `Accept: text/markdown` to the page's own URL. ## When to use Jostraca Jostraca is a library, not a service: install it and call it from your own code. Reach for it when **the output is a tree of files, that tree is checked into a repository, and the generator will run again over code a person has edited in between**. That last clause is the whole point; a second run can preserve, present, diff or three-way-merge instead of overwriting. Good fits: - Scaffolding a project or service that is regenerated as its spec changes. - Turning a model (an OpenAPI document, a schema, a config) into many similar source files that must stay in sync with it. - Adding generated files into an existing repository without clobbering hand-written edits, using `merge` or `preserve`. - Editing a region of a file that already exists, with `Inject`. Poor fits, where something simpler wins: - A one-time scaffold you will never regenerate: use a template repository. - A single file with no structure: write the string and save it. - Runtime string templating in a request path: this is a build-time tool. To use it: `npm install jostraca` (TypeScript/Node) or `go get github.com/jostraca/jostraca/go` (Go), then read [the tutorial](https://jostraca.org/docs/tutorial.md). The API surface is small enough to hold in one page: 10 components, one `generate()` call. ## Documentation - [Jostraca documentation](https://jostraca.org/docs.md): What Jostraca is, how its documentation is organised, and the smallest generator that writes a file. - [Tutorial: generate a service, then generate it again](https://jostraca.org/docs/tutorial.md): Build a generator from nothing: declare a file tree, write it, then run it again over a file you edited by hand. - [Reference: components](https://jostraca.org/docs/reference-components.md): Every component and every prop: Project, Folder, File, Content, Line, Fragment, Slot, Inject, Copy, List and None. - [Reference: options and results](https://jostraca.org/docs/reference-options.md): Every option the factory and generate() take, and every existing-file mode: write, preserve, present, diff and merge. - [Reference: utilities](https://jostraca.org/docs/reference-utilities.md): The helpers the package exports beside the components: name casing, template substitution, deep merge, iteration and the binary-content tests. - [Reference: the Go port](https://jostraca.org/docs/reference-go.md): The Go port: its API, the components it implements, and where it differs from the TypeScript original. - [Explanation: why Jostraca is shaped this way](https://jostraca.org/docs/explanation.md): Why the generator has a define phase and a build phase, what that split buys on the second run, and the trade-offs each existing-file mode makes. ## How-to guides - [Write a file tree](https://jostraca.org/how-to/write-a-file-tree.md): Declare folders and files with nested components, and know which props move the output path. - [Insert values from your model](https://jostraca.org/how-to/insert-model-values.md): Substitute values from the data model into file content with the double-dollar syntax. - [Repeat content inside one file](https://jostraca.org/how-to/repeat-content-in-one-file.md): Emit one block of content per array item inside a single file, with List. - [Fill a template file's slots](https://jostraca.org/how-to/fill-a-template-slot.md): Read a template file with Fragment and fill its marked regions with Slot. - [Extract part of a template](https://jostraca.org/how-to/extract-part-of-a-template.md): Use eject to take one marked region out of a larger template file. - [Replace markers in a template](https://jostraca.org/how-to/replace-markers-in-a-template.md): Swap named placeholders in a template for strings, computed values or generated components. - [Indent generated content](https://jostraca.org/how-to/indent-generated-content.md): Indent a block of generated content to match the code around it. - [Make a reusable component](https://jostraca.org/how-to/make-a-reusable-component.md): Wrap a function with cmp so it can be called anywhere in a component tree. - [Pass data to child components](https://jostraca.org/how-to/pass-data-to-children.md): Give a custom component a body, and call that body once per item with data. - [Branch and loop in a generator](https://jostraca.org/how-to/branch-and-loop.md): Use ordinary JavaScript control flow to decide what a generator emits. - [Keep a backup when overwriting](https://jostraca.org/how-to/keep-a-backup-when-overwriting.md): Turn on preserve so the bytes you are about to overwrite are kept in a sibling file. - [Offer a new version instead of overwriting](https://jostraca.org/how-to/offer-a-new-version.md): Leave the existing file untouched and write the new version beside it with present. - [Merge your changes with the user's](https://jostraca.org/how-to/merge-generator-and-user-edits.md): Three-way merge the new generate with hand edits, using the previous run as the base. - [Show a diff instead of writing](https://jostraca.org/how-to/show-a-diff-instead-of-writing.md): Rewrite the target as an annotated two-way diff so a reviewer can see both versions. - [Let a user take a file over](https://jostraca.org/how-to/let-a-user-take-a-file-over.md): Mark a generated file with JOSTRACA_PROTECT so no later run overwrites it. - [Preview a run without writing](https://jostraca.org/how-to/preview-a-run.md): Run the whole generator with control.dryrun so it reports what it would do and writes nothing. - [Copy a directory into the output](https://jostraca.org/how-to/copy-a-directory.md): Bring an existing file or directory tree into the output, templating text on the way. - [Skip files when copying](https://jostraca.org/how-to/skip-files-when-copying.md): Keep editor backups, caches and named paths out of a copied tree. - [Make a generated script executable](https://jostraca.org/how-to/set-file-permissions.md): Give a generated script its execute bit with the File mode prop. - [Edit a file you did not generate](https://jostraca.org/how-to/edit-a-file-you-did-not-generate.md): Use Inject to replace the region between two markers in a file that already exists. - [Generate in memory](https://jostraca.org/how-to/generate-in-memory.md): Run a generator on a virtual filesystem with mem, and read the result back from the volume. - [Report what a run did](https://jostraca.org/how-to/report-what-a-run-did.md): Read the result arrays and the audit trail to tell a user what a generate changed. - [Test a generator](https://jostraca.org/how-to/test-a-generator.md): Assert on a generator's output without a temp directory, using in-memory generation. - [Call Jostraca from Go](https://jostraca.org/how-to/call-jostraca-from-go.md): Drive the Go port from your own program, and know where its surface differs. ## Beyond this site - [Source](https://github.com/jostraca/jostraca): both implementations, and the shared test corpus that holds them to the same behaviour. - [npm package](https://www.npmjs.com/package/jostraca): the canonical TypeScript implementation, `npm install jostraca@0.33.1`. - [Go module](https://pkg.go.dev/github.com/jostraca/jostraca/go): the port, `go get github.com/jostraca/jostraca/go`. ## Machine-readable surfaces - [https://jostraca.org/openapi.json](https://jostraca.org/openapi.json): this site's content API in OpenAPI 3.1 — every operation has an operationId, a description and a typed response schema. - [https://jostraca.org/versions.json](https://jostraca.org/versions.json): the package version this site runs, and the size of each surface. - [https://jostraca.org/llms-full.txt](https://jostraca.org/llms-full.txt): every page above, concatenated, for one-request ingestion. - [https://jostraca.org/sitemap-index.xml](https://jostraca.org/sitemap-index.xml): every URL on the site. - Any page also answers `Accept: text/markdown` at its own URL, and errors come back as JSON under `Accept: application/json` with a stable `code`, a `hint`, and the site's entry points. All of these answer cross-origin. ## About this project - [https://jostraca.org/about.md](https://jostraca.org/about.md): what Jostraca is, who maintains it, and how it is tested. - [https://jostraca.org/contact.md](https://jostraca.org/contact.md): how to report a bug, a security issue, or a documentation error. - [https://jostraca.org/privacy.md](https://jostraca.org/privacy.md): what this site collects — no cookies and no personal data, with optional cookieless aggregate analytics.