Installation

Routa ships as three packages: a core library of route helpers, a CLI that validates and runs projects, and a scaffolder for new applications. This page covers installing them into an existing project. For a new project, the scaffolder installs everything for you.

Before You Start

• Node.js 24 or later:

  node --version

  v24.x.x

• Any of npm, pnpm, Yarn, or Bun. Routa does not write a lockfile or a packageManager field, so dependency tooling stays under your team’s control.

• New projects include .nvmrc so version managers select the supported runtime.

Steps

1. Install the runtime dependencies. hono and zod are peer dependencies of @routa-ts/core, so install them alongside it.

   npm

   npm install @routa-ts/cli @routa-ts/core hono zod

   pnpm

   pnpm add @routa-ts/cli @routa-ts/core hono zod

   yarn

   yarn add @routa-ts/cli @routa-ts/core hono zod

   bun

   bun add @routa-ts/cli @routa-ts/core hono zod

   @routa-ts/cli, @routa-ts/core, hono, and zod added to dependencies.

2. Install the development dependencies used by generated Routa apps.

   npm

   npm install --save-dev @biomejs/biome @types/node tsx typescript vitest

   pnpm

   pnpm add --save-dev @biomejs/biome @types/node tsx typescript vitest

   yarn

   yarn add --dev @biomejs/biome @types/node tsx typescript vitest

   bun

   bun add --dev @biomejs/biome @types/node tsx typescript vitest

   @biomejs/biome, @types/node, tsx, typescript, and vitest added to devDependencies.

3. Add the scripts that generated apps use.

   package.json

   {
     "scripts": {
       "dev": "routa dev",
       "start": "routa start",
       "generate": "routa generate",
       "check": "routa check",
       "build": "routa build",
       "test": "vitest run",
       "scaffold": "routa scaffold openapi.yaml",
       "openapi:check": "routa openapi check"
     }
   }

4. Create the Routa configuration entry point. Routa requires this file to exist, even when it is empty of options.

   src/routa.ts

   import { createRouta } from "@routa-ts/core";
   
   export default createRouta({
     port: 3000,
   });

5. Include both source and generated metadata in TypeScript compilation.

   tsconfig.json

   {
     "include": ["src/**/*.ts", ".routa/**/*.ts"]
   }

Verify

Run a check. Routa validates the project layout before it looks at any route file, so this confirms the install even with no routes yet.

npm

npx routa check

pnpm

pnpm exec routa check

yarn

yarn exec routa check

bun

bunx routa check

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

The Packages

Package	Role
@routa-ts/core	Route, middleware, config, logger, and query helpers used by your source and by generated code.
@routa-ts/cli	The routa binary for checks, generation, builds, scaffolding, and the dev server.
create-routa-ts	Project scaffolder invoked through your package manager’s create command.

Troubleshooting

Problem	Fix
ROUTA_PROJECT_REQUIRED: Missing src/routa.ts.	Create src/routa.ts with a default createRouta() export, as in step four.
TypeScript cannot find .routa/routes.gen.ts types.	Add .routa/**/*.ts to include in tsconfig.json, then run routa generate.
Peer dependency warnings for hono or zod.	Install both explicitly. @routa-ts/core declares them as peers rather than bundling them.

CLI in dependencies

Generated Routa apps keep @routa-ts/cli in dependencies rather than devDependencies so routa start is available in a deployed environment. If your deployment supplies start tooling another way, you can move it later.

Adding Routa to an Existing Hono App

Routa owns the HTTP route tree and the server lifecycle, so it replaces your Hono bootstrap rather than mounting beside it. Migrate one endpoint at a time: move the handler’s HTTP concerns into a route contract under src/routes/, and leave services, persistence, and domain logic where they are.

Next Steps

Create a projectSkip manual setup and scaffold a complete starter app.

First routeWrite the smallest useful route contract.

ConfigurationEvery option src/routa.ts accepts.