tsoa-next

tsoa-next continues the original tsoa project. The original repository and its contributors established the stable TypeScript-first and OpenAPI-first foundation this work builds on. Where historical release notes or migration references still point upstream, they are kept intentionally for provenance.

• TypeScript controllers and models as the single source of truth for your API
• A valid OpenAPI (formerly Swagger) spec (2.0 or 3.0 if you choose 😍) is generated from your controllers and models, including:
  • Paths (e.g. GET /users)
  • Definitions based on TypeScript interfaces (models)
  • Parameters/model properties marked as required or optional based on TypeScript (e.g. myProperty?: string is optional in the OpenAPI spec)
  • jsDoc supported for object descriptions (most other metadata can be inferred from TypeScript types)
• Routes are generated for middleware of choice
  • Express, Hapi, and Koa currently supported, other middleware can be supported using a simple handlebars template
  • Validate request payloads

• Rely on TypeScript type annotations to generate API metadata if possible
• If regular type annotations aren't an appropriate way to express metadata, use decorators
• Use jsdoc for pure text metadata (e.g. endpoint descriptions)
• Minimize boilerplate
• Models are best represented by interfaces (pure data structures), but can also be represented by classes
• Runtime validation of tsoa-next should behave as closely as possible to the specifications that the generated OpenAPI 2/3 schema describes. Any differences in validation logic are clarified by logging warnings during the generation of the OpenAPI Specification (OAS) and/or the routes.
  • Please note that by enabling OpenAPI 3 you minimize the chances of divergent validation logic since OpenAPI 3 has a more expressive schema syntax.

@Validate(...) adds opt-in runtime authority for external schemas on supported controller method parameters.

• Supported forms: @Validate(schema), @Validate('zod', schema), @Validate({ kind: 'zod', schema })
• Supported libraries: zod, joi, yup, superstruct, io-ts
• io-ts installs: add fp-ts, and add io-ts-types as well if you rely on helpers like withMessage
• Supported parameter decorators: @Body, @BodyProp, @Query, @Queries, @Path, @Header, and @FormField / uploaded file params
• Behavior: TypeScript metadata still drives OpenAPI generation, while the external schema replaces built-in runtime validation for the decorated parameter subtree
• Compatibility: routes without @Validate(...) keep their current behavior

Generated RegisterRoutes(...) functions also accept an optional validation context so applications can provide translation or failure-formatting hooks:

RegisterRoutes(app, {
  validation: {
    translate: (key, params) => translateMessage(key, params),
    errorFormatter: failure => failure,
  },
})

import * as t from 'io-ts'
import { withMessage } from 'io-ts-types'
import { Body, Controller, Post, Route, Validate } from 'tsoa-next'

interface PositiveFloatBrand {
  readonly PositiveFloat: unique symbol
}

const PositiveFloat = withMessage(
  t.brand(t.number, (n): n is t.Branded<number, PositiveFloatBrand> => Number.isFinite(n) && n > 0, 'PositiveFloat'),
  () => 'validation.wager.amount.mustBePositiveFloat',
)

const WagerCodec = t.type({
  amount: PositiveFloat,
  outcome: t.Int,
})

type Wager = t.TypeOf<typeof WagerCodec>

@Route('wagers')
export class WagersController extends Controller {
  @Post()
  public createWager(
    @Body()
    @Validate('io-ts', WagerCodec)
    wager: Wager,
  ): Wager {
    return wager
  }
}

This feature is fully opt-in. If you do not use @Validate(...), existing interface/class models, generated routes, validation behavior, and error responses are unchanged.

• Requirements:
  • Node.js 22 or newer
  • npm 10 or newer
  • We verify support across the previous LTS, current LTS, and Node vNext in CI
• Documentation
• API Reference
• Getting started guide

• Import decorators, runtime helpers, and generated route support from tsoa-next
• Import programmatic generation APIs from tsoa-next/cli
• Use the tsoa binary for CLI generation commands

Check out the guides

See example controllers in the tests

See example models in the tests

To contribute (via a PR), please first see the Contributing Guide