Check and Build

Routa validates the route graph before TypeScript ever runs, so contract mistakes surface as named diagnostics instead of deep inference errors. This guide covers the four commands that validate, generate, and compile, and when to reach for each.

Before You Start

• A project that installs cleanly, since check and build shell out to tsc.
• .routa/**/*.ts included in tsconfig.json, or generated context types will not resolve.

Steps

1. Validate the route graph and typecheck. This is the command to run before every commit.

   npm

   npm run check

   pnpm

   pnpm run check

   yarn

   yarn run check

   bun

   bun run check

2. Refresh generated metadata on its own when you changed route structure and want the .routa/ diff as a separate reviewable step.

   npm

   npm run generate

   pnpm

   pnpm run generate

   yarn

   yarn run generate

   bun

   bun run generate

3. Compile to JavaScript when you are ready to deploy.

   npm

   npm run build

   pnpm

   pnpm run build

   yarn

   yarn run build

   bun

   bun run build

4. Print the resolved route table when you want to see what Routa actually registered.

   npm

   npx routa routes

   pnpm

   pnpm exec routa routes

   yarn

   yarn exec routa routes

   bun

   bunx routa routes

Verify

routa check reports both phases and exits 0:

Routa validation passed for 4 route file(s).
Running TypeScript check: tsc -p tsconfig.json --noEmit
TypeScript check passed.
Routa check passed.

routa build emits JavaScript only after validation passes:

Routa build passed for 4 route file(s).

What Each Command Does

Command	Validates	Writes routes.gen.ts	Runs TypeScript
routa check	Yes	On success	tsc --noEmit
routa generate	Yes	On success	No
routa build	Yes	On success	tsc with emit
routa routes	Yes	On success	No

Validation is the same in all four. It covers project structure, route discovery, duplicate paths, missing 2xx responses, duplicate schema names, handler result shapes, middleware ordering, middleware reject statuses, and deprecation replacement targets. See Diagnostics for every code these can produce.

In Continuous Integration

Because a successful validation rewrites .routa/routes.gen.ts, treat a dirty working tree after generation as a failure. That catches a commit where source and metadata disagree:

npm

npx routa generate

pnpm

pnpm exec routa generate

yarn

yarn exec routa generate

bun

bunx routa generate

git diff --exit-code -- .routa
test -z "$(git ls-files --others --exclude-standard -- .routa)"

npm

npx routa check

pnpm

pnpm exec routa check

yarn

yarn exec routa check

bun

bunx routa check

npm

npx routa openapi breaking

pnpm

pnpm exec routa openapi breaking

yarn

yarn exec routa openapi breaking

bun

bunx routa openapi breaking

Troubleshooting

Problem	Fix
ROUTA_PROJECT_REQUIRED	Run the command from the project root. Routa requires package.json, tsconfig.json, src/, and src/routa.ts.
TypeScript errors about ctx properties that should exist	Metadata is stale. Run routa generate and typecheck again.
routa build reports no errors but dist/ is empty	tsconfig.json sets noEmit. Generated projects keep emit enabled for the build.
Validation passes locally and fails in CI	.routa/ was not committed. It is required, not a build artifact.

v0 status

Validation, metadata generation, TypeScript checks, builds, and route-table output are implemented in v0. These commands refresh .routa/routes.gen.ts after a clean validation, so CI must compare the generated diff.

Next Steps

DiagnosticsEvery validation error, its cause, and its fix.

Run and startMove from a passing build to a running server.

TestingCover behavior that validation cannot check.