Skip to content
Routa

Run and Start

Routa has two ways to run a project. routa dev runs TypeScript through tsx and restarts on every source change, but it does not emit the production dist/ build. routa start runs the JavaScript you already built. Both validate the route graph first, so a broken contract never reaches the server.

Before You Start

Section titled “Before You Start”
  • A project that passes routa check.
  • For start, a completed routa build.

Steps

Section titled “Steps”

  1. Run in development while editing. Routa validates routes, writes .routa/routes.gen.ts, typechecks, and starts the server through tsx.

    Terminal window
    npm run dev

  2. Edit any file under src/. The supervisor detects the change, revalidates, and restarts the runtime.

    Restarting Routa dev server...

  3. Build before running in production mode.

    Terminal window
    npm run build

  4. Start the built runtime. This runs dist/, does not typecheck, and does not compile.

    Terminal window
    npm run start

Verify

Section titled “Verify”

The default logger reports a successful start:

[2026-01-01T00:00:00.000Z] INFO api.started Routa API started. {"host":"127.0.0.1","port":3000,"routes":4}

Each completed request is logged at info, so a curl should produce a second line:

[2026-01-01T00:00:00.000Z] INFO http.request Request completed. {"method":"GET","path":"/status","status":200,"durationMs":1.42}

Development Versus Production

Section titled “Development Versus Production”
routa dev routa start
Source src/ through tsx dist/ JavaScript
Typecheck Yes, before starting No
Restart on change Yes No
Empty route files Stubbed with a valid contract Not stubbed
Requires a build No Yes

Creating an empty route.ts in development is deliberate: Routa fills it with a valid stub contract so the file compiles while you decide what it should contain. It prints the path it stubbed.

Stubbed src/routes/reports/route.ts

Troubleshooting

Section titled “Troubleshooting”
Problem Fix
Missing compiled runtime output for src/routes/users/route.ts. Run routa build first. start compares each source file against its dist/ output. Build first.
Compiled runtime output for … is stale. Run routa build first. A source file is newer than its compiled output. Rebuild.
The dev server keeps serving old behavior after an edit Validation failed. The diagnostics are printed and the previous process keeps running until source validates again.
The server exits immediately with no diagnostics The port is in use. api.start_failed is logged at error with the host and port.

Next Steps

Section titled “Next Steps”
DeployHost, port, and container shape for a production run.
ConfigurationSet host, port, logger, and lifecycle headers.
Runtime behaviorExact request and response semantics.