HazelJS vs NestJS

TL;DR

• NestJS is a proven TypeScript framework for APIs and microservices — excellent structure, mature ecosystem.
• AI on NestJS usually means bolting on LangChain, Vercel AI SDK, or custom OpenAI clients yourself.
• HazelJS keeps Nest-familiar modules, decorators, and DI, and ships Agent OS: DNA packages, crash-safe HITL, Skillgate, and local apply in the same backend.
• Choose NestJS when you only need classic backends or are deeply locked into Nest packages.
• Choose HazelJS when durable agents are a core product surface — clone Meridian to see the path.

Who this is for

You should read this if you:

• Know NestJS and want agents without a second framework + glue
• Are evaluating NestJS alternatives for durable LLM / agent backends
• Want one DI container for HTTP controllers and AgentRuns

Stay on NestJS if you:

• Ship mostly CRUD/API services with little AI
• Depend heavily on Nest-specific community modules you cannot replace yet
• Cannot afford a migration window for an existing large Nest monorepo

The problem NestJS does not solve alone

NestJS gives you controllers, providers, modules, guards, and pipes. For production agents you still assemble:

1. An LLM SDK (OpenAI, Anthropic, …)
2. A chain/agent library (often LangChain)
3. Approval / HITL that survives restarts
4. Packaging for prompts and policies
5. How REST becomes governed tools

That stack works — and it is a lot of glue. Teams end up with two mental models: Nest for HTTP, LangChain for AI.

Side-by-side comparison

Code: Nest-style HTTP vs Agent OS execute

Classic Nest-style controller feel in HazelJS:

import { Controller, Get, Post, Body, HazelModule } from '@hazeljs/core';
import { AITask } from '@hazeljs/ai';

@Controller({ path: '/chat' })
class ChatController {
  @AITask({ provider: 'openai', model: 'gpt-4o' })
  @Post()
  async chat(@Body() body: { message: string }) {
    return body.message;
  }

  @Get('health')
  health() {
    return { ok: true };
  }
}

@HazelModule({ controllers: [ChatController] })
export class AppModule {}

Agent OS execute (no separate LangChain executor):

import { Agent, Tool } from '@hazeljs/agent';

@Agent({
  name: 'support-agent',
  systemPrompt: 'You are a helpful support agent.',
  enableMemory: true,
  enableRAG: true,
})
export class SupportAgent {
  @Tool({
    description: 'Look up order by ID',
    parameters: [{ name: 'orderId', type: 'string', required: true }],
  })
  async lookupOrder(input: { orderId: string }) {
    return { status: 'shipped', trackingNumber: 'TRACK123' };
  }
}

Architecture decision

When NestJS is the better choice

Be honest with the tradeoff:

• Ecosystem gravity — Nest has more tutorials, jobs, and community packages.
• Team familiarity — rewriting working Nest services for AI you barely need is waste.
• Non-AI microservices — HazelJS still works, but Nest’s maturity may win on politics and hiring.

HazelJS wins when AI is a core product surface, not a side feature.

Migration path

Patterns map closely: modules → modules, providers → providers, controllers → controllers. Add @hazeljs/ai / @hazeljs/agent / @hazeljs/rag for AI slices first.

→ Full walkthrough: Migrate from NestJS to HazelJS.

FAQ

See the FAQ section on this page for structured answers (also exposed as FAQ schema for search).

Next steps

1. Clone Meridian — store:sync → platform:sync → dev
2. Read Agent OS overview and Agent OS guide
3. Compare the common combo stack: NestJS + LangChain vs HazelJS
4. Packages: Agent, Skillgate
5. Star / clone: github.com/hazel-js/hazeljs