---
title: "How-to guides"
description: "Task-oriented recipes: each guide solves one job you already have in mind, from composing a file tree to regenerating over code you edited."
source: "https://jostraca.org/how-to/"
---

# How-to guides

Each guide solves one task and assumes you know the basics — the [tutorial](https://jostraca.org/docs/tutorial) teaches those. The guides come from the generator repository, where the test suite runs every example in them or states why it does not.

## Compose the output tree

Declaring folders, files, and the content that goes inside them.

-   [Write a file tree](https://jostraca.org/how-to/write-a-file-tree)

    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)

    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)

    Emit one block of content per array item inside a single file, with List.

## Templates and fragments

Filling files from a data model, and from template files on disk.

-   [Fill a template file's slots](https://jostraca.org/how-to/fill-a-template-slot)

    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)

    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)

    Swap named placeholders in a template for strings, computed values or generated components.

-   [Indent generated content](https://jostraca.org/how-to/indent-generated-content)

    Indent a block of generated content to match the code around it.

## Reusable components

Factoring a generator into pieces you call more than once.

-   [Make a reusable component](https://jostraca.org/how-to/make-a-reusable-component)

    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)

    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)

    Use ordinary JavaScript control flow to decide what a generator emits.

## Regenerating over existing files

Running the generator again over code a person has edited.

-   [Keep a backup when overwriting](https://jostraca.org/how-to/keep-a-backup-when-overwriting)

    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)

    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)

    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)

    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)

    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)

    Run the whole generator with control.dryrun so it reports what it would do and writes nothing.

## Files, copying and permissions

Getting existing assets into the output, and setting how they land.

-   [Copy a directory into the output](https://jostraca.org/how-to/copy-a-directory)

    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)

    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)

    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)

    Use Inject to replace the region between two markers in a file that already exists.

## Embedding Jostraca

Driving the generator from your own tool, in memory or on disk.

-   [Generate in memory](https://jostraca.org/how-to/generate-in-memory)

    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)

    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)

    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)

    Drive the Go port from your own program, and know where its surface differs.