Skip to main content
tsoa is a framework that uses TypeScript decorators to generate OpenAPI specifications and runtime route configurations from your TypeScript controllers and models.

​
Prerequisites

Before installing tsoa, ensure your development environment meets these requirements:

Node.js

Node.js version 18.0.0 or higher

TypeScript

TypeScript 5.2.2 or higher
tsoa requires experimentalDecorators and emitDecoratorMetadata to be enabled in your TypeScript configuration.

​
Package Installation

tsoa is available as npm packages. You can install it using your preferred package manager: 
npm install tsoa @tsoa/runtime
npm install --save-dev @tsoa/cli

​
Package Breakdown

tsoa consists of multiple packages that work together:
  • @tsoa/cli - Command-line tools for generating OpenAPI specs and routes
  • @tsoa/runtime - Runtime decorators and utilities used in your application code
  • tsoa - Meta-package that includes both CLI and runtime (alternative installation option)
You can install the tsoa meta-package instead of @tsoa/cli and @tsoa/runtime separately:
npm install tsoa

​
TypeScript Configuration

Configure your tsconfig.json to enable decorators and emit decorator metadata:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2018",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
The experimentalDecorators and emitDecoratorMetadata options are required for tsoa decorators to work correctly.

​
Project Structure Setup

Create a recommended directory structure for your tsoa project: 
mkdir -p src/controllers src/models
touch tsoa.json
Your project structure should look like: 
my-tsoa-app/
├── src/
│   ├── controllers/
│   │   └── userController.ts
│   ├── models/
│   │   └── user.ts
│   └── server.ts
├── tsoa.json
├── tsconfig.json
└── package.json

​
tsoa Configuration

Create a tsoa.json file in your project root to configure code generation:
tsoa.json
{
  "entryFile": "src/server.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "spec": {
    "outputDirectory": "./dist",
    "specVersion": 3
  },
  "routes": {
    "routesDir": "./src",
    "middleware": "express"
  }
}

​
Configuration Options

​
entryFile
string
required
Entry point of your application. tsoa uses this to find your controllers.
​
spec
object
required
Configuration for OpenAPI specification generation:
  • outputDirectory: Where to save the generated spec
  • specVersion: OpenAPI version (2 or 3)
​
routes
object
required
Configuration for route generation:
  • routesDir: Where to generate route files
  • middleware: Framework choice (express, koa, or hapi)

​
Framework-Specific Installation

Depending on your chosen web framework, install the appropriate dependencies: 
npm install express
npm install --save-dev @types/express
Set middleware to "express" in tsoa.json.

​
Build Scripts

Add tsoa generation commands to your package.json:
package.json
{
  "scripts": {
    "build": "tsoa spec-and-routes && tsc",
    "dev": "tsoa spec-and-routes && nodemon src/server.ts",
    "tsoa:spec": "tsoa spec",
    "tsoa:routes": "tsoa routes",
    "tsoa:spec-and-routes": "tsoa spec-and-routes"
  }
}

​
Available Commands

Generates only the OpenAPI specification file.
Generates only the route registration files.
Generates both spec and routes in a single command (recommended).

​
Verification

Verify your installation by running: 
npx tsoa --help
You should see the tsoa CLI help output listing available commands.

​
Next Steps

Quickstart Guide

Build your first API with tsoa

Controllers

Learn about controller decorators

Build docs developers (and LLMs) love

Get started for freeTalk to us