17. Stability and versions

Status: Applies from 1.0.0-rc.1. Before that, any 0.x release could change anything.

Avi.js follows Semantic Versioning. All packages share one version, so @avijs/core@1.4.0 and @avijs/client@1.4.0 were released together and work together.

What 1.x promises

Within 1.x, a minor or patch release does not break code that uses only the stable API:

• The documented exports of @avijs/core, @avijs/client, @avijs/testing, @avijs/security, @avijs/multipart, @avijs/openapi and @avijs/workers: names, parameters and the types you write against them.
• Documented behavior: route precedence, the order of hooks, middleware, guards and validation, the status codes this tutorial lists, default limits, and the JSON shape of error responses (statusCode, error, message, details).
• The CLI: npm create avi, and avi new, generate, dev, build, check, client and inject with their flags. A project generated by any 1.x CLI keeps working with later 1.x packages.

A minor release adds features. A patch release fixes bugs. A patch may still change behavior that was unsafe, such as a header that leaked information; that comes with a security advisory and a note in the changelog.

What it does not promise

• Experimental APIs, marked experimental in this tutorial, may change in a minor release. Today that is manifests: describeApp, the manifest option and avi manifest (chapter 10).
• The building-block packages @avijs/di, @avijs/http, @avijs/validation and @avijs/compiler. Core and the CLI are built on them and re-export what apps need; import from @avijs/core instead. Their own exports, such as Container or generateClient, may change in a minor release.
• Internal helpers that other packages need: fillPath and queryString in @avijs/client.
• Type-only fields whose names start with ~, such as ~schema. They carry types for avi client and are never set at runtime.
• Wording: the text of error messages, log lines and the startup summary may improve. Match on status codes, error classes and the error JSON shape, not on messages.
• Generated files: what avi client and avi inject write may change in a minor release, as long as it gives the same types and lists. Regenerate them after upgrading, or let avi dev do it.

Deprecations

Before anything stable is removed, it is marked @deprecated (your editor strikes it through), the changelog says what to use instead, and it keeps working for the rest of 1.x. Removals happen only in a major release.

Supported versions

What	Supported
Node.js	22.12 or newer; CI tests 22, 24 and 26 on Linux, 24 on Windows and macOS
TypeScript	5.8 or newer; CI tests 6.0
Avi.js 1.x	The latest 1.x release gets fixes, security fixes included

Dropping a Node.js version happens only in a major release, after that version has reached its end of life. Raising the minimum TypeScript version may happen in a minor release when newer types need it; the changelog says so.

Release channels

Stable releases are published to npm's latest tag, which npm install uses. Release candidates go to next: npm install @avijs/core@next tries one before it becomes the next stable release. Install every @avijs package from next then, such as npm install @avijs/security@next: a package from latest would bring its own copy of @avijs/core, and modules from one copy are not modules to the other.

Next

Coming from NestJS? See Avi.js for NestJS developers, or go back to the tutorial index.