Overview HazelJS

Build AI-native backends that feel like home. HazelJS is a TypeScript framework where Agent Runtime, Agentic RAG, and persistent memory aren’t add-ons—they’re built in. Ship stateful AI agents, intelligent APIs, and production-ready backends with a decorator-based API, dependency injection, and a modular architecture that scales from side project to enterprise.

What is HazelJS?

HazelJS is built for intelligent, stateful backend applications—the kind that reason, remember, and integrate with LLMs without glue code. Whether you’re building a RAG-powered API, a multi-agent workflow, or a classic REST service with a sprinkle of AI, HazelJS gives you one stack, one style, and one place to grow.

You get:

  • Agent Runtime — Stateful AI agents with tools, memory, and human-in-the-loop. Define agents and tools with decorators; the runtime handles orchestration.
  • Agentic RAG — Retrieval-augmented generation and vector search out of the box. Ingest docs, embed, and query with semantic and hybrid search.
  • Built-in AI — First-class integration with OpenAI, Anthropic, Gemini, Cohere, and Ollama. Swap providers or stream responses without rewriting your app.
  • Enterprise-grade foundation — Dependency injection, decorator-based API, modules, guards, interceptors, pipes, and testing support so you can move fast without cutting corners.

Core philosophy

HazelJS is designed around a few non-negotiables:

  • AI-Native — Agent Runtime, Agentic RAG, and persistent memory are part of the framework, not plugins. AI is in the design from day one.
  • Developer experience — A clean, declarative API: @Controller, @Get, @Agent, @Tool, @SemanticSearch. Learn once, use everywhere.
  • Type safety — Full TypeScript with compile-time safety and reflection-based DI. Fewer runtime surprises, better refactors.
  • Modularity — Use only what you need: @hazeljs/core, @hazeljs/ai, @hazeljs/agent, @hazeljs/rag, @hazeljs/auth, and dozens more. No monolith tax.
  • Production ready — Dependency injection, advanced routing, guards, interceptors, pipes, exception filters, and patterns that work at scale.

Architecture at a glance

HazelJS uses a modular, decorator-based architecture so your code stays organized and testable:

  1. Modules — Group features into modules. Each module declares controllers, providers, and imports; the framework wires everything together.
  2. Dependency injection — A single DI container manages providers (singleton, transient, request scope) and resolves dependencies automatically. No manual wiring.
  3. Request pipeline — Every HTTP request flows through: routing → middleware → guards → interceptors → pipes → controller handler → response. Exception filters catch and format errors in one place.

Key packages to know:

  • @hazeljs/core — The foundation: DI, routing, decorators, guards, interceptors, pipes.
  • @hazeljs/agent — Agent Runtime for stateful AI agents and tools.
  • @hazeljs/ai — AI integration (OpenAI, Anthropic, Ollama, and more).
  • @hazeljs/rag — Agentic RAG, vector stores, and semantic search.
  • @hazeljs/auth — JWT, guards, role hierarchy, and tenant isolation.

Technical details

  • Decorators — TypeScript decorators and reflect-metadata drive routing, DI, and behavior. You write @Controller('users'), @Get(), @Injectable(), @UseGuards(); the framework does the rest.
  • Request lifecycle — The router matches the request to a controller method; middleware, guards, interceptors, and pipes run in a clear order; the handler returns; exception filters shape the response when something goes wrong.
  • DI container — Constructor injection with reflection metadata. Define providers, declare dependencies, and get the right instances without boilerplate.

Next steps

Pick your path and jump in:

  • Installation — Install the CLI and core package and run your first app.
  • Concepts & Glossary — Core terms, decorators by package, and links to deep dives.
  • Controllers — Define routes, inject request data, and handle HTTP with decorators.
  • REST API Tutorial — Build a full API from scratch step by step.
  • Introduction — The full story: philosophy, architecture diagrams, comparisons, and a quick example.
  • API Reference — Complete list of core decorators, types, and APIs.