Introduction

Aventara is a contract-driven API framework for TypeScript. You describe your data once, in a Prisma schema, and Aventara turns it into a typed HTTP API and a typed frontend client:

1. Your ORM schema and your Aventara configuration compile into contracts. A contract is plain, serializable data that says exactly which Resources exist, which fields can be read, filtered, ordered or written, and which operations are available.
2. A NestJS host serves a typed HTTP protocol built from those contracts: find, create, update, delete and upsert operations for every Resource, plus transactions and a GET /_contract discovery endpoint.
3. A generator writes a typed client for your frontend from the deployed contract. Arguments and results are typed by the contract, so the frontend and the server work from the same contract.

THE ROUND TRIPONE CONTRACT. BOTH SIDES.

schema.prisma+aventara.config.ts

COMPILE

ContractsResources · fields · operations

01 / SERVER

NestJS host

Serves your contract & HTTP APIPOST /api/_resources/
User/find/many

02 / FRONTEND

Typed AvClient

Generated from the deployed contractavClient.User
.find.many(...)

GET /api/_contractavclient generate → typed client

HTTP requestclient → host → result

What you get

• find, create, update, delete and upsert for every Prisma model, with no controllers to write.
• A typed query language: filters, relation filters, select/include, ordering, pagination, nested counts and nested writes. Result types follow your select exactly (Results and typing).
• Interactive transactions with references between steps ($ref) (Transactions).
• Exposure per contract layer: hide fields, make fields write-only, switch operations off for the frontend only, or expose only what the frontend calls.
• Pipelines at every level (the layer, a Resource, an operation family or variant, a field): guards, pipes, hooks, interceptors and filters, with hooks that can write other rows in the same transaction. Which stage do I use? says which one fits a task.
• Field validators written with AvZ (maxLength, gte, email, ...), checked by the server and by the generated client before it sends.
• A generated frontend client with typed errors. It does not depend on any Aventara package at runtime (Frontend client).
• Typed Json fields: declare a shape once and every write is checked and the field is typed in server code and in the generated client (JSON fields).
• A stable response envelope with machine-readable codes (A1000, A2003, V1005, ...).
• The server refuses a client generated from an older contract with A2005. See Contract hash.

Packages

Which package goes where, and which are dev or runtime dependencies, is on Installation. In short:

Status

Aventara is a release candidate. The current release is 1.0.0-rc.12, published under the rc dist-tag. Install with @rc, as the commands in these docs do, so you get the newest release candidate:

npx @aventara/cli@rc new my-api

Until 1.0, a release candidate can still change the public API, including breaking changes; 1.0.0-rc.1 reshaped the configuration (Upgrading). Every change is listed in the Changelog with its upgrade steps. From 1.0 on, a breaking change needs a new major version. Pin exact versions (the generated projects already do) and read the Changelog before moving to the next release candidate.

Easy for tools to work with

A script, an editor or a code assistant can read and change an Aventara project from facts the project states:

• Every answer has a stable code (A2004), and every validation issue has its own code, the exact path in the request, and for a failed field validator the check's name and parameters ("check": "max_length", "params": { "maximum": 80 }). A tool can fix the argument the issue points at without parsing a sentence. See Error codes.
• The configuration is one typed object with one shape at every layer, and everything about a Resource sits under resources.<Resource>. A misplaced or misspelled key is a type error at that key, and startup errors name the path and the fix (restrictions moved in rc.1: use exposed + exemptions).
• The frontend client is generated and typed: its types come from the deployed contract, so a wrong field, operator or operation is a compile error before it is a request, and the contract itself (GET /api/_contract) is plain JSON that describes every operation.
• aventara new and aventara init give your AI coding agent the project's rules as an agent skill, with an AGENTS.md section pointing to it. See Working with AI agents.

Requirements

The full table and notes are on Installation. In short:

Where to go next

• Why Aventara: the same feature written with plain NestJS, GraphQL, tRPC and Aventara, and the tradeoffs.
• Installation: requirements and what each package is for.
• Getting started: a running API and a typed call in a few minutes.
• Add to an existing project: aventara init on a NestJS 12 project.
• Concepts: contracts, Resources, operations, results.
• License: free to use, including in commercial applications.

See also: Exposing and hiding fields, Authentication and guards, Deploying.