Avi.js 1.0 Is Here: My Open-Source TypeScript Framework Reaches Its First Stable Release 🚀💻
A few weeks ago, I started working on Avi.js, a lightweight TypeScript framework for building backend applications with Node.js.
It started with a simple question:
What if I could have the structured architecture of NestJS without requiring reflection-based dependency injection or unnecessary framework overhead?
That idea eventually became Avi.js.
After several releases, experiments, bug fixes, and improvements, I'm happy to share that Avi.js v1.0.0 is officially released!
This is the first stable release of the framework, and a milestone I've been working toward since the project started.
What is Avi.js?
Avi.js is an open-source, TypeScript-first backend framework for Node.js.
It takes inspiration from NestJS, particularly its modular architecture, controllers, services, and dependency injection.
However, Avi.js approaches a few things differently.
The framework is built around these ideas:
- Structure without the overhead. Provide useful architecture without forcing unnecessary abstractions.
- No required
reflect-metadata. Dependency injection works without runtime reflection.
- Two API styles. Choose standard TypeScript decorators or plain functions and objects.
- Native Node.js HTTP. Avi.js runs directly on
node:http, without Express or Fastify underneath.
- TypeScript-first development. Make use of TypeScript's type system for dependency injection, validation, and API clients.
- Early error detection. Catch dependency issues and route conflicts during application initialization.
The goal is to make backend development structured while keeping the framework understandable.
What's included in Avi.js 1.0?
Avi.js has grown quite a bit since its first release.
Here are some of the features now available.
1. Modules, controllers, and dependency injection
Avi.js supports a familiar modular architecture inspired by NestJS.
You can organize applications using modules, controllers, and services.
import {
Controller,
Get,
Module,
AviFactory,
} from '@avijs/core';
class UsersService {
findAll() {
return [{ id: 1, name: 'Joy' }];
}
}
@Controller('/users')
class UsersController {
constructor(private readonly users: UsersService) {}
@Get('/')
findAll() {
return this.users.findAll();
}
}
@Module({
controllers: [UsersController],
providers: [UsersService],
})
class AppModule {}
const app = await AviFactory.create(AppModule);
await app.listen(3000);
One of the important differences is how dependency injection works.
Avi.js doesn't require reflect-metadata or TypeScript's legacy decorator metadata.
Instead, avi dev and avi build can analyze constructor types and generate dependency lists in a plain TypeScript file called inject.gen.ts.
Developers can still define dependencies explicitly using static inject when they prefer more control.
This keeps dependency wiring visible and avoids relying on runtime reflection.
2. Two styles, one engine
Not everyone wants to use decorators.
That's why Avi.js also provides an explicit API using plain objects and functions.
Both approaches use the same underlying routing system, dependency injection container, and request pipeline.
You can start with a minimal application and introduce modules as your project grows.
3. Type-safe API clients
Avi.js includes a typed client generator.
npx avi client
The CLI analyzes your application's routes and generates API types that can be used with @avijs/client.
This helps provide autocomplete and type checking for routes, parameters, request bodies, and responses.
It also reduces the need to manually maintain separate API type definitions between the backend and frontend.
Avi.js includes tools for creating projects, generating resources, running development servers, building applications, and checking configuration.
Create a new application:
npm create avi@latest my-app
Generate a CRUD resource:
npx avi g resource posts
The resource generator creates the necessary files and registers the resource in your application.
5. Features for real backend applications
Beyond the core architecture, Avi.js includes:
- Schema validation using Standard Schema-compatible libraries, including Valibot and Zod
- Typed environment configuration
- Middleware and guards
- Rate limiting, CORS, and security headers
- Multipart file uploads with limits and MIME type restrictions
- Server-sent events
- OpenAPI 3.1 generation
- Testing utilities with provider overrides
- Worker and cluster support through
@avijs/workers
- Request IDs, structured logging, and graceful shutdown
These features were added gradually as the framework evolved.
From pre-release to stable
Getting to v1.0 wasn't just about adding more features.
A large part of the work involved reviewing the existing implementation, improving error handling, fixing edge cases, and making sure the framework behaved consistently.
During the release candidate phase, I focused on areas such as:
- Making generated dependency injection lists more reliable
- Preventing build tools from accidentally removing unrelated files
- Improving compatibility across different project configurations
- Fixing issues with streams, workers, and application startup
- Improving CLI diagnostics and generated code
- Expanding testing and documentation
One thing I've learned from working on a framework is that getting a feature to work is only part of the challenge.
Making it predictable, maintainable, and safe to use is another challenge entirely.
What does v1.0 mean?
For Avi.js, v1.0 marks the transition from early development to the first stable release.
It also establishes a clearer approach to versioning and compatibility.
This doesn't mean the framework is perfect or that development is finished.
There are still things to improve, edge cases to discover, and features worth exploring.
But reaching v1.0 means there's now a stable foundation to continue building on.
The project also has a dedicated guide explaining its stability and versioning expectations:
Stability and versions
Try Avi.js
You can get started with Node.js 22.12 or newer.
npm create avi@latest my-app
cd my-app
npm install
npm run dev
If you prefer a minimal project without the modular structure:
npm create avi@latest my-app -- --template minimal
Both templates use the same underlying framework.
What's next?
Reaching v1.0 is exciting, but I still consider Avi.js an ongoing learning experience.
Building a framework has given me a better understanding of dependency injection, HTTP routing, TypeScript tooling, code generation, security, and many other areas of backend development.
I'm looking forward to continuing to improve it, exploring new ideas, and learning from developers who decide to try it.
Avi.js is open source under the MIT license, and contributions, suggestions, bug reports, and feedback are always welcome.
If you're working with TypeScript and Node.js, feel free to give it a try.
This is just the beginning. 🚀
GitHub: https://github.com/chrischase011/avi-js
Documentation: https://chrischase011.github.io/avi-js/
Latest releases: https://github.com/chrischase011/avi-js/releases