https://github.com/tsoa-next/tsoa-next
Build type-safe OpenAPI APIs for Node.js using TypeScript decorators with automatic spec generation and validation
https://github.com/tsoa-next/tsoa-next
api-framework backend code-generation contract-first decorators express koa nodejs openapi rest-api schema-validation swagger tsoa tsoa-next type-safe typescript
Last synced: 2 days ago
JSON representation
Build type-safe OpenAPI APIs for Node.js using TypeScript decorators with automatic spec generation and validation
- Host: GitHub
- URL: https://github.com/tsoa-next/tsoa-next
- Owner: tsoa-next
- License: mit
- Created: 2026-02-25T15:33:04.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-03-29T01:10:11.000Z (6 days ago)
- Last Synced: 2026-03-29T01:12:39.931Z (6 days ago)
- Topics: api-framework, backend, code-generation, contract-first, decorators, express, koa, nodejs, openapi, rest-api, schema-validation, swagger, tsoa, tsoa-next, type-safe, typescript
- Language: TypeScript
- Homepage: http://tsoa-next.dev/
- Size: 7.81 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.MD
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
tsoa-next
Pronounced so·uh
OpenAPI-compliant REST APIs using TypeScript and Node
[](https://github.com/tsoa-next/tsoa-next/actions/workflows/runTestsOnPush.yml)
[](https://www.npmjs.com/package/tsoa-next)
[](https://sonarcloud.io/summary/new_code?id=tsoa-next_tsoa-next)
## Project Lineage
`tsoa-next` continues the original [`tsoa`](https://github.com/lukeautry/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.
## Goal
- 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
## Philosophy
- 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.
## External Validators
`@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:
```ts
RegisterRoutes(app, {
validation: {
translate: (key, params) => translateMessage(key, params),
errorFormatter: failure => failure,
},
})
```
```ts
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.isFinite(n) && n > 0, 'PositiveFloat'),
() => 'validation.wager.amount.mustBePositiveFloat',
)
const WagerCodec = t.type({
amount: PositiveFloat,
outcome: t.Int,
})
type Wager = t.TypeOf
@Route('wagers')
export class WagersController extends Controller {
@Post()
public createWager(
@Body()
@Validate('io-ts', WagerCodec)
wager: Wager,
): Wager {
return wager
}
}
```
## Migration Note
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.
## Getting Started
- 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](https://tsoa-next.dev/)
- [API Reference](https://tsoa-next.dev/reference/)
- [Getting started guide](https://tsoa-next.dev/getting-started)
## Package Surface
- 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
## Examples
Check out the [guides](https://tsoa-next.dev/)
See example controllers in [the tests](https://github.com/tsoa-next/tsoa-next/tree/main/tests/fixtures/controllers)
See example models in [the tests](https://github.com/tsoa-next/tsoa-next/blob/main/tests/fixtures/testModel.ts)
## Help wanted
### Contributing code
To contribute (via a PR), please first see the [Contributing Guide](https://github.com/tsoa-next/tsoa-next/blob/main/docs/CONTRIBUTING.md)