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

• 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

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

   npm

   npx routa scaffold openapi.yaml --preview

   pnpm

   pnpm exec routa scaffold openapi.yaml --preview

   yarn

   yarn exec routa scaffold openapi.yaml --preview

   bun

   bunx 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.

   npm

   npx routa scaffold openapi.yaml --yes

   pnpm

   pnpm exec routa scaffold openapi.yaml --yes

   yarn

   yarn exec routa scaffold openapi.yaml --yes

   bun

   bunx routa scaffold openapi.yaml --yes

6. Validate and review the diff before committing.

   npm

   npm run check

   pnpm

   pnpm run check

   yarn

   yarn run check

   bun

   bun run check

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.

git diff --name-only

.routa/manifest.json
.routa/openapi-baseline.json
.routa/routes.gen.ts
src/routes/users/route.ts

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	ROUTA_SCAFFOLD_MODIFIED_GENERATED_FILE
Yes	No	—	conflict, then ROUTA_SCAFFOLD_UNMANAGED_FILE

Framework-owned metadata under .routa/ is exempt. Routa always rewrites routes.gen.ts, manifest.json, and openapi-baseline.json, because those are derived files with no user content.

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.

v0 status

In v0, you can use manifest-based preview, conflict detection, and safe regeneration. Keep run bodies to a service call and an outcome choice; when logic lives in src/services/, reverting generated-file edits before regeneration is inexpensive.

Next Steps

Generated filesWhat the manifest records and why.

Scaffold from OpenAPIThe first-run workflow in full.

Check and buildValidate the result before committing.