tsoa-rules

TSOA Development Best Practices

This document outlines comprehensive guidelines and best practices for developing Node.js server-side applications with tsoa, focusing on TypeScript for type safety and OpenAPI specification generation.

1. Introduction to tsoa

• tsoa is a framework that integrates an OpenAPI compiler to build type-safe Node.js applications using TypeScript.
• It generates OpenAPI (Swagger) specifications and routes from your TypeScript controllers and models, ensuring type-safe by default and seamless runtime validation.
• Philosophy:
  • Rely on TypeScript type annotations for API metadata.
  • Use decorators for metadata not expressible via type annotations.
  • Utilize JSDoc for pure text metadata (e.g., endpoint descriptions).
  • Minimize boilerplate code.
  • Models should primarily be interfaces (pure data structures), but classes are also supported.

2. Project Setup and Configuration

tsoa.json Configuration

• Configure entryFile to point to your application's entry point (e.g., src/app.ts or src/index.ts).
• Use controllerPathGlobs to specify where tsoa should look for controllers (e.g., "src/**/*Controller.ts").
• Set noImplicitAdditionalProperties to "throw-on-extras" for strict validation, rejecting undeclared properties in incoming requests. Other options are "ignore" or "silently-remove-extras".
• Define spec.outputDirectory and routes.routesDir for generated OpenAPI specifications and route files.
• Set spec.specVersion to 3 for OpenAPI v3 specifications.

// tsoa.json
{
  "entryFile": "src/app.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "controllerPathGlobs": ["src/**/*Controller.ts"],
  "spec": {
    "outputDirectory": "build",
    "specVersion": 3
  },
  "routes": {
    "routesDir": "build"
  }
}

tsconfig.json Recommendations

• Ensure experimentalDecorators is true.
• Use strict type-checking options like strict, noImplicitAny, strictNullChecks, noUnusedLocals, and noUnusedParameters.