API Contrats #1

New issue

Open

opened 2026-05-09 05:20:30 +00:00 by araemer · 0 comments

araemer commented

2026-05-09 05:20:30 +00:00

Owner

The alternative in the shared-package world is something like ts-rest, which is worth knowing about. You define a contract object (routes, params, bodies, responses) in a shared package
using plain TypeScript — no decorators, no OpenAPI step. The backend implements the contract, the frontend consumes it with a typed client. It's lighter than tsoa and fits a plain Express
setup more naturally, but it does mean replacing the router layer with ts-rest's router.

So the real fork in the road is:

tsoa — OpenAPI spec as the artefact, decorators on controllers, code-gen for the frontend client
ts-rest — TypeScript contract object as the artefact, no code-gen, both sides bind to the same object directly

Both require touching the REST resource layer. The question is whether you want an OpenAPI spec (for docs, Swagger UI, non-TS consumers) or whether TypeScript-to-TypeScript safety is
sufficient.

For that level of sharing you really want a contract that describes the full endpoint surface, not just the DTOs. That's where tsoa earns its cost: the controller decorators encode the route, HTTP method, path params, auth requirements, and request/response types in one place, and the spec is generated from that rather than maintained separately. The alternative in the shared-package world is something like ts-rest, which is worth knowing about. You define a contract object (routes, params, bodies, responses) in a shared package using plain TypeScript — no decorators, no OpenAPI step. The backend implements the contract, the frontend consumes it with a typed client. It's lighter than tsoa and fits a plain Express setup more naturally, but it does mean replacing the router layer with ts-rest's router. So the real fork in the road is: - tsoa — OpenAPI spec as the artefact, decorators on controllers, code-gen for the frontend client - ts-rest — TypeScript contract object as the artefact, no code-gen, both sides bind to the same object directly Both require touching the REST resource layer. The question is whether you want an OpenAPI spec (for docs, Swagger UI, non-TS consumers) or whether TypeScript-to-TypeScript safety is sufficient.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

araemer/recipe-backend#1

No description provided.

Rows
Columns