Skip to content
Routa

Regenerate Safely

The second scaffold run is riskier than the first, because generated files now contain your handler code. Routa tracks a hash of everything it wrote in .routa/manifest.json and refuses to overwrite a file that no longer matches, so regeneration fails loudly rather than silently discarding work.

Before You Start

Section titled “Before You Start”
  • A committed working tree. Review is easier when the only diff is the regeneration.
  • The updated OpenAPI document.
  • .routa/manifest.json present. Without it, Routa treats every existing file as unmanaged.

Steps

Section titled “Steps”

  1. Preview. Routa requires this or an explicit --yes once a manifest exists, so a second run can never be accidental.

    Terminal window
    npx routa scaffold openapi.yaml --preview

  2. Read every entry marked ~ update. These are tracked files whose current content still matches the manifest and whose newly generated content would change. A tracked file that you edited instead triggers ROUTA_SCAFFOLD_MODIFIED_GENERATED_FILE; --yes never discards those edits. Move logic into application-owned code or revert the generated-file edits before regenerating.

  3. Resolve entries marked ! conflict. Routa will not write over a file it does not track. Move your version aside, or restore the manifest if the file really was generated.

  4. Decide about entries marked - remove. These correspond to operations no longer in the document. Routa deletes tracked files it generated; anything you created stays.

  5. Apply.

    Terminal window
    npx routa scaffold openapi.yaml --yes

  6. Validate and review the diff before committing.

    Terminal window
    npm run check

Verify

Section titled “Verify”

git diff should contain only files that appeared in the preview. A change to a file the preview did not mention means the manifest is out of date with reality.

Terminal window
git diff --name-only
.routa/manifest.json
.routa/openapi-baseline.json
.routa/routes.gen.ts
src/routes/users/route.ts

How Routa Decides

Section titled “How Routa Decides”

For each file it is about to write, Routa compares three things: whether the file exists, whether the manifest tracks it, and whether its current hash matches the recorded one.

Exists Tracked Hash matches Result
No — — add
Yes Yes Yes update or unchanged
Yes Yes No or missing hash ROUTA_SCAFFOLD_MODIFIED_GENERATED_FILE
Yes No — conflict, then ROUTA_SCAFFOLD_UNMANAGED_FILE

Framework-owned .routa/routes.gen.ts and .routa/manifest.json are exempt. Routa can regenerate them without a matching recorded hash. The OpenAPI baseline still requires ownership and hash checks.

A missing manifest hash also blocks removal of an existing stale file. Restore the manifest from version control and preserve local edits before regenerating. --yes does not bypass these checks, and known conflicts block all writes and deletions.

Troubleshooting

Section titled “Troubleshooting”
Problem Fix
Refusing to overwrite modified generated file Move your edits into an application-owned module, then re-run. Handler logic belongs in services, which is what makes routes regenerable.
Refusing to overwrite unmanaged file Rename your file, or restore .routa/manifest.json from version control if it was lost.
Preview shows everything as conflict The manifest is missing. Restore it from git rather than deleting your source.
A route you deleted from the document still serves traffic Regeneration removed the file but metadata is stale. Run routa generate.

Next Steps

Section titled “Next Steps”
Generated filesWhat the manifest records and why.
Scaffold from OpenAPIThe first-run workflow in full.
Check and buildValidate the result before committing.