Skip to content
Routa

Create a Project

create-routa-ts generates a complete TypeScript Routa application: a working route with schemas and a test, Biome and TypeScript configuration, an OpenAPI starter document, and the committed .routa/ metadata that Routa checks against.

Before You Start

Section titled “Before You Start”
  • Node.js 24 or later.
  • A directory where the new project folder can be created.

Steps

Section titled “Steps”

  1. Run the scaffolder. It detects the package manager that invoked it and uses that one for installation and for the commands it prints at the end.

    Terminal window
    npm create routa-ts@latest

    A successful run ends with the target directory it created:

    Your Routa app is ready in 'routa-app'.

  2. Answer the prompts. Every prompt has a matching flag if you would rather not be asked.

    Prompt Flags Default
    Project name positional argument routa-app
    Include a starter OpenAPI file? --openapi / --no-openapi include
    Initialize a new git repository? --git / --no-git yes when interactive
    Install dependencies? --install / --no-install yes when interactive
    Continue with these settings? --yes / -y skips it —

  3. Enter the project directory.

    Terminal window
    cd routa-app
    pwd
    …/routa-app

  4. Install dependencies if you declined the install prompt.

    Terminal window
    npm install

    Confirm the install produced the dependency tree:

    Terminal window
    test -d node_modules && echo "Dependencies installed."
    Dependencies installed.

  5. Start the development server.

    Terminal window
    npm run dev

    A successful start emits the api.started lifecycle event with the bound host and port:

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

Verify

Section titled “Verify”

The generated /status route responds immediately:

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

What It Creates

Section titled “What It Creates”
  • .nvmrc
  • .gitignore
  • biome.json
  • package.json
  • tsconfig.json
  • openapi.yaml starter document, omitted with --no-openapi
  • Directorysrc/
    • routa.ts
    • Directoryroutes/
      • Directorystatus/
        • route.ts
        • schemas.ts
        • route.test.ts
  • Directory.routa/
    • manifest.json
    • openapi-baseline.json
    • routes.gen.ts

The .routa/ files are only generated when the starter OpenAPI document is included. Without it, run routa generate once to produce route metadata.

Non-Interactive Use

Section titled “Non-Interactive Use”

In CI or a script, pass every flag so the scaffolder never prompts:

Terminal window
npm create routa-ts@latest my-api -- --yes --no-git --no-install
 
Your Routa app is ready in 'my-api'.

Troubleshooting

Section titled “Troubleshooting”
Problem Fix
Command "<manager> install" did not run successfully. The project files were still written. Enter the directory and install manually.
git init failed. Git is missing or the directory is inside an existing repository. The project itself is fine; re-run git init yourself if you want one.
The wrong package manager appears in the output. Detection reads npm_config_user_agent. Invoke the scaffolder through the create command of the manager you want.
The target directory already exists and is not empty. Choose a different project name, or clear the directory first.

Next Steps

Section titled “Next Steps”
Project anatomyUnderstand every file the scaffolder wrote.
First routeAdd your own route beside the generated one.
Scaffold from OpenAPIGenerate routes from a real OpenAPI document.