Introduction

AxilJS is a complete JavaScript/TypeScript backend ecosystem for building production-ready APIs and backend systems without assembling a large collection of unrelated packages.

It brings the core layers of a backend into one consistent platform:

HTTP server, routing, middleware, SSE, and static files
PostgreSQL, MySQL, and SQLite ORM with migrations
Authentication, password hashing, and RBAC
Schema-based request validation
WebSockets, rooms, and realtime communication
Events, queues, scheduling, retries, and circuit breakers
Logging, metrics, tracing, and health checks
AI providers, RAG, agents, vector storage, and MCP
Memory monitoring and automatic optimization
Multi-tenancy, audit logs, feature flags, and deployment tooling
Built-in API response handling
ORM Studio for visual API and database inspection

Note

AxilJS requires Node.js 18+, npm 8+, and TypeScript 5+.

Why AxilJS?

A typical Node.js backend is assembled from many independently designed libraries. That can work, but it also creates repeated decisions around conventions, configuration, validation, responses, security, testing, and infrastructure.

AxilJS takes a different approach: provide these capabilities as a coordinated ecosystem under the @axiljs package scope.

text

One ecosystem
      │
      ├── HTTP + Routing
      ├── Security + Validation
      ├── Auth + RBAC
      ├── ORM + Migrations
      ├── Events + WebSockets
      ├── Queue + Scheduling
      ├── Resilience + Observability
      ├── AI + RAG + Agents
      ├── Cloud + Deployment
      ├── Memory Management
      └── ORM Studio

The result is a backend foundation where the major building blocks share the same ecosystem, conventions, and tooling.

The AxilJS philosophy

AxilJS is built around three principles:

One ecosystem

Core backend capabilities are developed and distributed under the @axiljs scope.

Production-oriented defaults

Security, validation, observability, resilience, testing, and deployment are treated as first-class backend concerns rather than afterthoughts.

Grow without replacing the foundation

AxilJS supports different application structures, including MVC, monolithic applications, and microservice-oriented systems.

Where the name comes from

AxilJS is derived from SyntaxilitY:

text

Synt + axil + itY + JS
       ────
       agility through syntax
       natural point of growth
       SyntaxilitY signature

The word axil also refers to the point on a plant where new growth begins. The idea behind the name is simple: AxilJS provides a central foundation from which a backend can grow naturally.

Part	Meaning
`axil`	Extracted from SyntaxilitY; associated with agility and natural growth
`itY`	SyntaxilitY signature
`JS`	JavaScript

What is included?

AxilJS is organized into focused packages that work together as one ecosystem.

Package	Purpose
`@axiljs/core`	HTTP server, router, middleware, SSE, static files, response manager
`@axiljs/config`	Environment loading and typed configuration
`@axiljs/security`	Helmet, rate limiting, CSRF, and sanitization
`@axiljs/orm`	PostgreSQL, MySQL, and SQLite ORM with migrations
`@axiljs/auth`	JWT, password hashing, authentication, and RBAC
`@axiljs/validation`	Schema-based request validation
`@axiljs/testing`	Test runner, assertions, and HTTP test client
`@axiljs/events`	In-process event bus and pub/sub
`@axiljs/websocket`	RFC 6455 WebSocket server and rooms
`@axiljs/queue`	Message queues, scheduling, retries, and delayed jobs
`@axiljs/circuit`	Circuit breaker, retry, and timeout utilities
`@axiljs/observability`	Logging, metrics, tracing, and health checks
`@axiljs/ai`	AI providers, RAG, agents, vector storage, and MCP
`@axiljs/cloud`	Multi-tenancy, audit logs, feature flags, and deployment
`@axiljs/memory`	Memory monitoring, leak detection, GC, and optimization
`@axiljs/pm`	Package management, lock files, and checksums
`@axiljs/studio`	Browser-based developer dashboard
`@axiljs/cli`	Project creation, development, testing, building, and deployment commands

A minimal AxilJS application

Create a project with the AxilJS CLI:

Terminal

axil create my-api

cd my-api

npm install

axil run

The development server starts the application and watches the source tree for changes.

text

AxilJS development server
─────────────────────────────────────
 
✓ Server running at http://localhost:3000
✓ Studio running at http://localhost:3001
✓ Watching src/ for changes

Info

ORM Studio runs on appPort + 1 by default. If your application runs on port 3000, Studio is available at http://localhost:3001.

A simple API

AxilJS provides a conventional application API while keeping common response handling built in.

typescript

import { Application, cors } from '@axiljs/core'
import { loadEnv, defineConfig } from '@axiljs/config'
import { helmet, rateLimit } from '@axiljs/security'
 
loadEnv()
 
const config = defineConfig({
  PORT: { type: 'number', default: 3000 },
  NODE_ENV: { type: 'string', default: 'development' }
})
 
const app = new Application({
  server: { port: config.PORT }
})
 
app.use(helmet())
app.use(cors({ origin: '*' }))
app.use(rateLimit({ max: 100, windowMs: 60000 }))
 
app.get('/health', (req, res) => {
  res.success(
    { uptime: process.uptime() },
    'Healthy'
  )
})
 
app.get('/users/:id', (req, res) => {
  res.success(
    { id: req.params.id },
    'User fetched'
  )
})
 
app.post('/users', (req, res) => {
  res.created(
    req.body,
    'User created'
  )
})
 
app.listen()

Common response methods include:

typescript

res.success(data, message)
res.created(data, message)
res.paginated(items, total, page, limit, message)
 
res.badRequest(message)
res.unauthorized(message)
res.forbidden(message)
res.notFound(message)
res.conflict(message)
res.validationError(message)
 
res.serverError(message)
res.tooManyRequests()
res.serviceUnavailable()

typescript

res.HTTP_200_OK(users, 'Users fetched');
 
res.HTTP_201_CREATED(user, 'User created');
 
res.HTTP_400_BAD_REQUEST('Invalid request');
 
res.HTTP_401_UNAUTHORIZED('Invalid token');
 
res.HTTP_403_FORBIDDEN('Permission denied');
 
res.HTTP_404_NOT_FOUND('User not found');
 
res.HTTP_409_CONFLICT('Email already exists');
 
res.HTTP_500_INTERNAL_SERVER_ERROR('Database error');
 
res.HTTP_503_SERVICE_UNAVAILABLE('Service unavailable');
 
res.HTTP_204_NO_CONTENT();
 
res.HTTP_405_METHOD_NOT_ALLOWED();
 
res.HTTP_406_NOT_ACCEPTABLE();
 
res.HTTP_415_UNSUPPORTED_MEDIA_TYPE();
 
res.HTTP_429_TOO_MANY_REQUESTS();
 
res.HTTP_422_UNPROCESSABLE_ENTITY();

This keeps API responses consistent across application modules.

ORM and database support

The AxilJS ORM supports:

PostgreSQL
MySQL
SQLite
Migrations
Query and repository abstractions

A basic model can be defined with decorators:

typescript

import {
  createConnection,
  Entity,
  Column,
  PrimaryKey,
  BaseRepository
} from '@axiljs/orm'
 
@Entity('users')
class User {
  @PrimaryKey()
  id: number
 
  @Column({ type: 'string', length: 255 })
  name: string
 
  @Column({ type: 'string', unique: true })
  email: string
}
 
const db = await createConnection({
  driver: 'postgres',
  url: process.env.DATABASE_URL
})
 
class UserRepository extends BaseRepository<User> {
  constructor() {
    super(User, db)
  }
}
 
const users = new UserRepository()
 
const user = await users.create({
  name: 'Tariq',
  email: 'tariq@syntaxility.dev'
})

ORM Studio

AxilJS includes ORM Studio, a browser-based developer dashboard designed to make local API and database development easier.

Run:

Terminal

axil run

Studio automatically starts alongside the application.

It provides:

Capability	Description
API Explorer	Discover routes and use the built-in Try It Out interface
Database Browser	Inspect tables, columns, constraints, and paginated data
SQL Query Editor	Run read-only SQL queries with syntax highlighting
Realtime Monitor	Inspect WebSocket connections and SSE streams
Collection Export	Export Postman, Insomnia, and OpenAPI collections
QR Access	Open the application or Studio from another device on the same network

Studio supports SQLite, PostgreSQL, and MySQL.

Built for backend architectures

AxilJS is not tied to a single application architecture.

You can organize an application as:

text

MVC
 │
 ├── models
 ├── views
 ├── controllers
 └── routes

or as a modular monolith:

text

Application
 │
 ├── Auth
 ├── Users
 ├── Products
 ├── Orders
 └── Payments

or evolve toward distributed services:

text

API Gateway
     │
 ┌───┼───────────┐
 │   │           │
Auth Users    Orders
 │               │
 └────── Events ─┘

The framework provides the backend capabilities; the application architecture remains yours to choose.

Development workflow

The AxilJS CLI provides the main development lifecycle:

Terminal

axil create my-api

axil run

axil build

axil test

axil deploy

axil install @axiljs/orm

axil doctor

During development, axil run watches the source tree and recompiles changed files automatically.

text

01:30:02 [axil run] Compiled project
          ✓ Server running at http://localhost:3000
          ✓ Studio running at http://localhost:3001
 
01:31:15 [axil run] Changed: controllers/UserController.ts
01:31:15 [axil run] Compiled changed file(s)
01:31:15 [axil run] Restarting

From HTTP to AI

AxilJS extends beyond the HTTP layer.

The ecosystem includes infrastructure for:

text

HTTP
 │
 ├── Auth + RBAC
 ├── Validation
 ├── ORM
 ├── Events
 ├── WebSockets
 ├── Queues
 ├── Resilience
 ├── Observability
 ├── AI / RAG / Agents / MCP
 ├── Cloud / Multi-tenancy
 └── Memory Management

For AI applications, @axiljs/ai provides provider integrations, RAG pipelines, vector storage, agents, and tools.

typescript

import {
  OpenAIProvider,
  RAGPipeline,
  VectorStore,
  Agent,
  calculatorTool
} from '@axiljs/ai'
 
const provider = new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY
})
 
const rag = new RAGPipeline({
  provider,
  vectorStore: new VectorStore()
})
 
const agent = new Agent({
  provider,
  tools: [calculatorTool],
  maxIterations: 10
})

Deployment

AxilJS can generate deployment artifacts through the CLI:

Terminal

axil deploy

The generated deployment structure can include:

text

deploy/
├── Dockerfile
├── deployment.yaml
└── deploy.sh

You can then build and run the application directly or deploy it with Docker and Kubernetes.

Terminal

npm run build

node dist/main.js

docker build -t my-api .

docker run -p 3000:3000 --env-file .env my-api

kubectl apply -f deploy/deployment.yaml

What makes AxilJS different?

AxilJS is not intended to replace JavaScript itself or force one architectural style.

Its purpose is to provide a coherent backend foundation with the infrastructure commonly required by production applications.

text

Traditional approach
 
Framework
   +
ORM
   +
Auth library
   +
Validation library
   +
Queue
   +
WebSocket library
   +
Observability
   +
AI SDKs
   +
Custom tooling
   +
Deployment scripts
 
 
AxilJS
 
        ┌─────────────────────────┐
        │         AxilJS          │
        │                         │
        │ HTTP · ORM · Auth       │
        │ Validation · Events     │
        │ WebSockets · Queue      │
        │ Resilience · Metrics    │
        │ AI · Cloud · Memory     │
        │ Studio · CLI            │
        └─────────────────────────┘

The goal is straightforward: less ecosystem assembly, more application development.

Tip

Start with the Quick Start to create your first AxilJS application and have a development server running in minutes.

Next steps

Quick Start — Create your first AxilJS application
CLI — Learn the axil command-line workflow
Core — Explore the HTTP server and routing layer
ORM — Work with PostgreSQL, MySQL, and SQLite
Authentication — Add JWT authentication and RBAC
ORM Studio — Explore the visual development dashboard