Skip to content
Routa

Quickstart

This guide creates a new Routa project, starts it in development mode, and runs the same checks Routa expects before you ship. The generated app already contains a working /status route, so you have a request to make at the end of step three.

Before You Start

Section titled “Before You Start”
  • Node.js 24 or later. Check with node --version.
  • npm, pnpm, Yarn, or Bun. Routa does not write a lockfile or a packageManager field.

Steps

Section titled “Steps”

  1. Create a Routa project. The scaffolder asks for a project name and whether to include a starter OpenAPI file, a git repository, and installed dependencies.

    Terminal window
    npm create routa-ts@latest
     
    Your Routa app is ready in 'routa-app'.

  2. Enter the project. If you answered no to the install prompt, run the install command below; otherwise skip it.

    Terminal window
    cd routa-app
    pwd
    …/routa-app
    Terminal window
    npm install
    Terminal window
    test -d node_modules && echo "Dependencies installed."
    Dependencies installed.

  3. Start development mode.

    Terminal window
    npm run dev

    routa dev validates the route graph, writes .routa/routes.gen.ts, typechecks the project, and starts the server on http://127.0.0.1:3000.

    INFO api.started Routa API started. {"host":"127.0.0.1","port":3000,"routes":1}

  4. Run the checks used before shipping.

    Terminal window
    npm run generate
    npm run check
    npm run build
    npm run test
    npm run openapi:check
     
    Generated .routa/routes.gen.ts for 1 route file(s).
    Routa check passed.
    Routa build passed for 1 route file(s).
    Test Files  1 passed (1)
    OpenAPI check passed. No drift detected.

Verify

Section titled “Verify”

Request the generated status route in a second terminal:

Terminal window
curl http://127.0.0.1:3000/status
{ "ok": true }

A successful routa check reports the validated route count and exits with code 0:

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

Troubleshooting

Section titled “Troubleshooting”
Problem Fix
Routa commands must run inside a TypeScript Routa project. Run the command from the project root, the directory holding package.json and src/routes.
The server starts on a port already in use. Set PORT for one run, or change port in src/routa.ts.
routa openapi check reports missing .routa/openapi-baseline.json. You created the project without the starter OpenAPI file. Run routa scaffold openapi.yaml or skip the OpenAPI check.
Editing a route does not change the response. routa dev restarts on changes under src/. If validation failed, the diagnostics appear in the dev output and the previous server keeps running.

Next Steps

Section titled “Next Steps”
Project anatomyLearn which files you own and which files Routa owns.
First routeWrite your own route contract from scratch.
Route contractsUnderstand the model behind every Routa HTTP boundary.
CLI referenceEvery command and flag the routa binary accepts.