Generated Files

Routa writes exactly three files, all inside .routa/. They hold what Routa learned from your source: the route table, a record of what scaffolding generated, and the accepted OpenAPI contract. Commit all three.

• Directory.routa/

  • routes.gen.ts route table and type augmentation
  • manifest.json scaffold tracking and content hashes
  • openapi-baseline.json accepted OpenAPI contract

How It Works

Every command that validates a project also refreshes routes.gen.ts when validation passes, so check, build, dev, and generate can all legitimately change your working tree. Validation runs first: a project with diagnostics leaves the previous file untouched rather than writing partial metadata.

The other two files change only when you ask. manifest.json is written by routa scaffold, and openapi-baseline.json is written by routa scaffold and by routa openapi breaking --update-baseline.

The Files

.routa/routes.gen.ts

Exports routaRoutes, an array describing every route: file, path, methods, response statuses, declared input sources, middleware chains, provided context keys, reject outcomes, groups, and segments. The runtime loads it to register routes, and the CLI reads it during checks.

It also augments the Register interface from @routa-ts/core. That augmentation is what makes createRouteRoot("/users/:userId") know the context available at that path, and what lets a deprecation.replacement pointing at a local path be checked in the editor.

Refresh it after adding, moving, or removing a route file, changing which methods a route declares, or changing middleware layout:

routa generate

Generated .routa/routes.gen.ts for 4 route file(s).

.routa/manifest.json

Records each file scaffolding produced, along with its source operationId, its kind, and a hash of the content Routa wrote. Regeneration compares current file contents against those hashes to classify each file as an update, unchanged, a conflict with your edits, or a removal — which is what makes routa scaffold --preview trustworthy.

.routa/openapi-baseline.json

The OpenAPI contract your team has accepted. routa openapi check compares the freshly generated document against it to detect drift, and routa openapi breaking uses it to detect removed operations and newly required inputs. It supplies info and components.schemas to generation. It retains servers as baseline-owned metadata, but the v0 generator does not emit that field.

Rules

• Commit .routa/. It is the shared reference that makes drift checks and regeneration safety work across machines and in CI.
• Review its diff like source. A change in routes.gen.ts is a change to your API surface.
• Never edit routes.gen.ts or manifest.json by hand; the next command overwrites them.
• Generation is deterministic. Identical source produces identical output, so an unexpected diff means an unexpected contract change.

Limits

Generated metadata is only as fresh as the last successful command. A stale routes.gen.ts produces confusing type errors, because context types come from the generated file rather than from the source Routa has not read yet. When types disagree with the code in front of you, run routa generate first.

Commands write to the working tree

routa check, routa build, and routa dev all synchronize routes.gen.ts after a successful validation. In CI, run routa generate and fail the job if git status reports changes, rather than assuming checks are read-only.

v0 status

In v0, commit routes.gen.ts, manifest.json, and openapi-baseline.json. After you change source, refresh generated metadata; Routa does not run a remote metadata service.

Next Steps

Regenerate safelyPreview scaffold changes before accepting them.

Check and buildWhich command refreshes metadata and when.

Project anatomyHow generated files relate to the source you own.