DEV Community

Cover image for HazelJS 1.0.0: Stable Release of the AI-Native TypeScript Framework
Muhammad Arslan
Muhammad Arslan

Posted on

HazelJS 1.0.0: Stable Release of the AI-Native TypeScript Framework

#ai #news #node #typescript

Today we are shipping HazelJS 1.0.0 — the first stable release of our AI-native TypeScript framework for Node.js. All 47 @hazeljs/* packages are published to npm under the latest dist-tag with a formal semver guarantee.

If you have been building on HazelJS since the beta line (0.8.x), this is the release we have been working toward: a cohesive platform you can depend on in production, not a collection of experimental packages.

What 1.0.0 means

HazelJS 1.0.0 is not a marketing bump. It is a commitment:

Promise What it means for you
Semver stability Patch and minor releases within 1.x will not introduce breaking API changes
npm latest npm install @hazeljs/core resolves to the stable line — no @beta tag required
47 packages, one version Every @hazeljs/* package ships at 1.0.0 with aligned peer dependency ranges
Production gates CI enforces format, typecheck, lint, build, unit tests, and integration tests on Node 20, 22, and 23
Documented upgrades Breaking changes from the 0.9.0 cleanup are documented below with migration paths

The journey: beta to stable

HazelJS grew quickly from a focused core (@hazeljs/core, @hazeljs/ai, @hazeljs/agent, @hazeljs/rag) into a 47-package monorepo covering everything from durable workflows and distributed sagas to Stripe payments, GraphQL, Kafka, and an in-browser runtime inspector.

Through 0.3.x–0.8.x, we shipped under the npm beta dist-tag while the API surface matured. That period gave us:

  • Real-world feedback from starters, examples, and early adopters
  • Time to deprecate legacy APIs cleanly in 0.9.0
  • Coverage and CI hardening before calling the platform stable

1.0.0 is the line in the sand: the APIs you adopt today are the APIs we maintain under semver.

Platform stability

Continuous integration

Every push and pull request runs the full pipeline:

  1. Format check (Prettier)
  2. Typecheck (TypeScript project references across the monorepo)
  3. Lint (ESLint)
  4. Build (tiered dependency order)
  5. Unit tests (all workspaces)
  6. Integration tests (DI lifecycle, auth flows, AI task execution)
  7. Coverage upload (Codecov)

The CI matrix tests against Node.js 20.x, 22.x, and 23.x — matching the engines declared across packages (>=20.0.0).

Test coverage thresholds

Core packages now enforce minimum 60% coverage thresholds in CI, including:

  • @hazeljs/core, @hazeljs/cli, @hazeljs/gateway, @hazeljs/pdf-to-audio
  • Packages that previously had no thresholds: kafka, pubsub, swagger, serverless, typeorm, i18n, saga, distributed-lock, and others

This does not mean every line is tested — it means regressions in critical paths are far less likely to slip through unnoticed.

Integration tests

Unit tests validate packages in isolation. Integration tests in tests/integration/ validate cross-package behavior:

  • DI lifecycle — module bootstrap, provider resolution, singleton consistency
  • Auth — JWT sign/verify, claim normalization for OAuth/SAML-style identities
  • AI tasks — @AITask decorator execution through AIEnhancedService

These tests catch the kind of wiring bugs that unit tests alone miss.

Supply chain and release automation

  • npm audit in CI at --audit-level=high
  • Trusted Publisher (OIDC) — packages publish from GitHub Actions without long-lived npm tokens
  • Provenance — publish attestations via npm publish --provenance
  • Idempotent publish — partial publish failures can be retried; already-published versions are skipped automatically

Security posture (unchanged, now stable-contract)

HazelJS 1.0.0 carries forward the production security stack from earlier releases:

  • Rate limiting, CSRF, CORS, and security headers
  • Graceful shutdown and structured health checks
  • @hazeljs/guardrails for PII redaction, toxicity detection, and factuality checks
  • @hazeljs/casl for policy-based authorization
  • @hazeljs/audit for tamper-evident audit trails

What changed in 1.0.0

Release engineering

  • Default npm dist-tag changed from beta → latest
  • scripts/bump-version.js now syncs devDependencies and lerna.json
  • Repository URLs normalized to hazel-js/hazeljs
  • All ecosystem starters and examples bumped to ^1.0.0

Breaking changes (landed in 0.9.0)

If you are upgrading from 0.8.x, apply these changes before or during your move to 1.0.0:

@hazeljs/ai — AIService removed

The legacy AIService class is removed. Use AIEnhancedService instead.

// Before (0.8.x)
import { AIService } from '@hazeljs/ai';

// After (1.0.0)
import { AIEnhancedService } from '@hazeljs/ai';
Enter fullscreen mode Exit fullscreen mode

The @AITask decorator now requires AIEnhancedService in the DI container. Task execution logic lives in AITaskExecutor, invoked via AIEnhancedService.executeTask().

@hazeljs/agent — circuit breaker re-export removed 

// Before
import { CircuitBreaker } from '@hazeljs/agent';

// After
import { CircuitBreaker } from '@hazeljs/resilience';
Enter fullscreen mode Exit fullscreen mode

@hazeljs/swagger — AutoSwaggerOptions removed 

// Before
import { AutoSwaggerOptions } from '@hazeljs/swagger';

// After
import { SwaggerBuildOptions } from '@hazeljs/swagger';
Enter fullscreen mode Exit fullscreen mode

@hazeljs/rag — AgenticGraphSearchResult removed 

// Before
import { AgenticGraphSearchResult } from '@hazeljs/rag';

// After
import { GraphSearchResult } from '@hazeljs/rag'; // graph module export
Enter fullscreen mode Exit fullscreen mode

@hazeljs/data — PipelineBuilder factory helpers removed 

// Before
PipelineBuilder.create().reset();

// After
const builder = new PipelineBuilder();
// use builder directly; no .reset() — create a new instance instead
Enter fullscreen mode Exit fullscreen mode

The full 1.0.0 package line

All 47 packages release at 1.0.0:

Core & DX: core, cli, config, prompts, eval, inspector, i18n

AI & Intelligence: ai, agent, rag, ml, memory, guardrails, mcp, ops-agent, pdf-to-audio

Workflows & Data: flow, flow-runtime, data, saga, worker, cron, queue

APIs & Messaging: graphql, grpc, kafka, pubsub, messaging, websocket, realtime, event-emitter, serverless

Infrastructure: auth, oauth, casl, cache, prisma, typeorm, discovery, gateway, resilience, distributed-lock, observability, audit, feature-toggle, payment, swagger

Highlights by layer

Application core (@hazeljs/core)

Decorator-based modules, advanced DI (singleton, transient, request scope), routing with wildcards and versioning, global middleware, graceful shutdown, and health checks — the foundation everything else builds on.

AI stack

  • @hazeljs/ai — Multi-provider LLM API (OpenAI, Anthropic, Gemini, Cohere, Ollama), streaming, HCEL orchestration, HazelAI platform integration
  • @hazeljs/agent — Stateful agents, tool calling, supervisor patterns, human-in-the-loop, MCP and A2A support
  • @hazeljs/rag — 11 document loaders, vector stores, GraphRAG, agentic retrieval, memory integration
  • @hazeljs/prompts — Versioned prompts with hot-swap from Redis or database
  • @hazeljs/flow — Durable execution graphs with WAIT/resume, idempotency, and optional Prisma persistence

Production operations

  • @hazeljs/inspector — Framework-aware DevTools UI served from your running app
  • @hazeljs/observability — OpenTelemetry tracing, cost monitoring, reasoning-loop debugging
  • @hazeljs/gateway — API gateway with metrics and routing
  • @hazeljs/saga + @hazeljs/distributed-lock — Distributed transactions and cross-service locking

Upgrade guide

From 0.8.x (recommended path) 

# 1. Update dependencies
npm install @hazeljs/core@^1.0.0 @hazeljs/ai@^1.0.0
# ... repeat for packages you use, or update package.json ranges to ^1.0.0

# 2. Apply breaking changes from 0.9.0 (see above)

# 3. Run your test suite
npm test
Enter fullscreen mode Exit fullscreen mode

Fresh start 

npx @hazeljs/cli g app my-app --template=ai-native
cd my-app
npm install
npm run dev
Enter fullscreen mode Exit fullscreen mode

Browse 40+ starters at hazeljs.ai/starters — all updated to ^1.0.0.

What we are optimizing for in 1.x

HazelJS 1.0.0 optimizes for teams shipping AI-native backends in TypeScript who want:

  1. One stack — routing, auth, AI, agents, RAG, workflows, and observability without glue code
  2. Modular adoption — install only the packages you need; peer dependencies keep versions aligned
  3. Production defaults — security middleware, health checks, guardrails, and resilience patterns built in
  4. Stable contracts — semver guarantees so upgrades are predictable

We are not claiming every edge case is solved. We are claiming the platform contract is stable, the release process is automated and auditable, and the upgrade path from beta is documented.

What's next

Post-1.0 work on the roadmap includes:

  • Performance benchmarks and publishable latency numbers
  • Expanded E2E coverage beyond integration tests
  • Flow package coverage raised toward 80%
  • 2.0 microservices platform features (service mesh integration, enhanced discovery)

Join us on Discord to shape what comes next, file issues on GitHub, and star the repo if HazelJS is useful to you.

Links

HazelJS 1.0.0 — one framework, AI built in, stable on npm latest.

Top comments (0)