# Installation [#installation]

You rarely install Aventara packages by hand. `aventara new` (or `aventara init`) adds the server packages to a NestJS project, and `avclient init` adds the generator to your frontend. This page lists what that puts where, so you know what is in your `package.json` and why.

## Requirements [#requirements]

|                      | Supported                                                    |
| -------------------- | ------------------------------------------------------------ |
| Node.js              | `^22.23.4 \|\| >=24.22.1` (on Node 22, use npm 11 or newer)  |
| NestJS               | 12                                                           |
| ORM                  | Prisma `^7.10.1`                                             |
| Database             | SQLite or PostgreSQL                                         |
| Package manager      | npm or pnpm (yarn is not supported)                          |
| TypeScript, server   | 6 (`>=5.7.0 <7`)                                             |
| TypeScript, frontend | `>=5.7.0`, TypeScript 7 included                             |
| Module format        | ESM and CommonJS projects (a fresh NestJS 12 project is ESM) |

The bins refuse to run on an unsupported Node, in one sentence that names the range.

## Packages [#packages]

| Package                     | Install it                                                        | Where                                   | What it is                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ----------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@aventara/cli`             | Do not. Run it with `npx` (or `pnpm dlx`), or install it globally | Your machine                            | The `aventara` command: `aventara new <name>` creates a NestJS 12 project with Aventara; `aventara init` adds Aventara to an existing one. It is not a dependency of your project.                                                                                                                                           |
| `@aventara/core`            | Added for you                                                     | Server, dependency                      | The framework: configuration, contract compilation, validation, execution, transactions. Its `@aventara/core/protocol` entry exposes the HTTP protocol as plain data and functions. Transport- and ORM-agnostic.                                                                                                             |
| `@aventara/prisma7-adapter` | Added for you                                                     | Server, dependency                      | The Prisma 7 adapter for SQLite and PostgreSQL, plus `describePrismaAdapter` and the `aventara-prisma7-generate` bin that runs on install (`aventara:prepare`).                                                                                                                                                              |
| `@aventara/build`           | Added for you                                                     | Server, dev dependency, same version    | The `aventara-build` bin, which `aventara:prepare` runs after the adapter's generate step. It writes the Resource tree, the computed-fields file and the prebuilt Contracts ([Deploying](/framework/docs/deploying#build-time-contracts)). Nothing in your deployed application imports it. Needs `typescript` `>=5.7.0 <7`. |
| `@aventara/nest`            | Added for you                                                     | Server, dependency                      | Hosts a framework in NestJS 12 on Express or Fastify: `AventaraModule`, `@InjectFramework()`.                                                                                                                                                                                                                                |
| `@aventara/mcp`             | Optional                                                          | Server, dependency, same version        | The MCP server: your `agent` layer as tools an AI agent calls. `@aventara/nest` mounts it when the configuration has `mcp` ([MCP](/framework/docs/mcp)).                                                                                                                                                                     |
| `@aventara/client`          | `avclient init` adds it                                           | Frontend, dev dependency, exact version | The `avclient` generator. Not needed at runtime: the generated client imports nothing from it.                                                                                                                                                                                                                               |
| `@aventara/testing`         | Optional                                                          | Server, dev dependency                  | Conformance fixtures and a fake in-memory adapter, for testing code that runs a framework without a database, or an adapter, a host or a client against the protocol ([Testing and conformance](/framework/docs/testing-and-conformance)).                                                                                   |

The server's runtime dependencies are `@aventara/core`, `@aventara/nest` and `@aventara/prisma7-adapter`, all at the same exact version, together with Prisma (`@prisma/client`, a driver adapter, and `prisma` as a dev dependency). Your frontend ships only its own code and the generated client. `@aventara/core` itself depends on `zod`, which only its `@aventara/core/avz` entry (typed JSON fields and field validators: [JSON fields](/framework/docs/json-fields), [Field validators](/framework/docs/field-validators)) ever loads.

Each package ships its `CHANGELOG.md` beside its README, so the release notes for the version you installed are in `node_modules/@aventara/<package>/`.

### Server side [#server-side]

A project made by `aventara new` has this in `package.json`. The Aventara versions are exact; Prisma and the driver are written at the adapter's range `^7.10.1`, so the first install takes the newest Prisma 7 and never Prisma 8:

```json
{
  "dependencies": {
    "@aventara/core": "1.0.0-rc.12",
    "@aventara/nest": "1.0.0-rc.12",
    "@aventara/prisma7-adapter": "1.0.0-rc.12",
    "@prisma/adapter-better-sqlite3": "^7.10.1",
    "@prisma/client": "^7.10.1"
  },
  "devDependencies": { "@aventara/build": "1.0.0-rc.12", "prisma": "^7.10.1" },
  "scripts": {
    "aventara:prepare": "aventara-prisma7-generate --schema prisma/schema.prisma --client src/generated/prisma --provider sqlite --driver @prisma/adapter-better-sqlite3 --out src/generated/aventara/discovery.artifact.ts --config src/aventara.config.ts && aventara-build",
    "postinstall": "npm run aventara:prepare",
    "prebuild": "npm run aventara:prepare",
    "prestart": "npm run aventara:prepare",
    "prestart:dev": "npm run aventara:prepare",
    "prestart:debug": "npm run aventara:prepare"
  }
}
```

With PostgreSQL the driver is `@prisma/adapter-pg`. `aventara:prepare` runs three things in order: `prisma generate`, the adapter's discovery step (`aventara-prisma7-generate`), then `aventara-build`. Between them they write `src/generated/aventara/discovery.artifact.ts`, `resources.generated.ts`, `computed-fields.generated.ts` and `contracts.generated.ts`. The `postinstall` script runs it on a plain `npm install`, and the `prebuild`, `prestart`, `prestart:dev` and `prestart:debug` scripts run it before `npm run build` and the start scripts, so a schema change needs no separate step. npm and pnpm run these `pre` hooks; Yarn Berry, and pnpm with `enable-pre-post-scripts=false`, do not, so run `aventara:prepare` yourself there (pnpm projects get `pnpm run aventara:prepare` in these scripts). Run `npm run aventara:prepare` yourself after changing `prisma/schema.prisma`, and after adding or upgrading a package by name (`npm install <package>` did not run `postinstall` with npm 11.19).

### Frontend side [#frontend-side]

```bash
npx @aventara/client@rc init
```

adds `@aventara/client` as an exact dev dependency, an `avclient:generate` script, `framework.client.ts`, an `.env` entry and `.env` in the frontend's `.gitignore`, then generates the client. The frontend needs a `tsconfig.json` (plain JavaScript projects are not supported yet). `typescript` is an optional peer: with it installed, the generated output is type-checked with your own copy after generation. Without it, the check is syntax and shape only, and a warning says so.

## Creating a project [#creating-a-project]

```bash
npx @aventara/cli@rc new my-api        # npm
pnpm dlx @aventara/cli@rc new my-api   # pnpm
```

Use the `@rc` tag: it points to the newest release candidate (`1.0.0-rc.12`). The CLI runs a pinned `nest new`, adds Aventara, installs, and commits the result (`Initial Aventara Scaffold`, unless git is missing or unconfigured, the directory is already inside a repository, or you pass `--skip-git`). It picks the package manager from the lockfile, else the one that launched it, else npm, and never touches a database. `aventara --version` prints the CLI's version; `--orm` takes `prisma7`. See [Getting started](/framework/docs/getting-started), or [Add to an existing project](/framework/docs/existing-project).

## Package manager and Node notes [#package-manager-and-node-notes]

* npm and pnpm are both supported. Under pnpm, the CLI also writes `pnpm-workspace.yaml` with the build-script allowances Prisma and the SQLite driver need, and next steps print `pnpm exec prisma db push` and `pnpm dlx` forms. Yarn is not supported.
* Node 22 needs npm 11 or newer. The npm 10 bundled with older Node 22 cannot install Nest 12's own scaffold. Check with `npm -v` and upgrade with `npm install -g npm@11`.
* Node 24: `>=24.22.1` is supported. A new project is ESM and runs its e2e tests with Vitest (`vitest.config.e2e.ts`). A CommonJS project still uses Jest, and its Jest e2e setup needs Node 24.9 or newer, a limit that comes from Nest and Jest.
* TypeScript: the server side needs TypeScript 5.7 or later and below 7 (the `aventara new` scaffold uses 6). The frontend generator works with `>=5.7.0`, TypeScript 7 included.
* Pin exact versions. Aventara is a release candidate and its API can still change before 1.0, so the generated projects already pin exactly. Keep `@aventara/client` at the same version as the server.

## Install safely [#install-safely]

Commit your lockfile and install with it, so every machine and every deploy gets the versions you tested:

```bash
npm ci                          # npm
pnpm install --frozen-lockfile  # pnpm
```

npm 11 may print `npm warn install-scripts ... @prisma/engines, prisma ... not yet covered by allowScripts` after the install. It is expected, and the install still works.

Hold back brand-new versions with a release-age delay.

```ini
# .npmrc (npm 11.10 or later; days)
min-release-age=3
```

```yaml
# pnpm-workspace.yaml (pnpm; minutes)
minimumReleaseAge: 4320
```

The units differ: npm counts days, pnpm counts minutes. Both examples above mean three days.

A release-age delay also holds back a brand-new Aventara release, including a fresh `@rc`. Exclude the Aventara packages (`minimumReleaseAgeExclude` in pnpm, `min-release-age-exclude` in npm) or wait out the delay.

When an advisory names a fixed version, exclude that exact version so you get it at once (pnpm takes `name@x.y.z`; npm excludes by package name); remove the exclude after 3 days.

After installing, check the registry signatures of what you installed:

```bash
npm audit signatures
```

Aventara releases are published with two-factor authentication on the maintainer's npm account. They do not carry build provenance attestations or signed git tags yet.

## See also [#see-also]

* [Why Aventara](/framework/docs/why-aventara)
* [Getting started](/framework/docs/getting-started)
* [Frontend client](/framework/docs/frontend-client)
* [CLI reference](/framework/docs/cli-reference)
* Guides: [Deploying](/framework/docs/deploying), [Upgrading](/framework/docs/upgrading)