Getting Started

Introduction

What AxilJS is, the 22 @axiljs packages it ships, its 10 project templates, and how it fits a modern TypeScript backend.

10 min readUpdated DocumentationEdit this page
On this page17

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
  • Cluster mode, capacity planning, and Kubernetes manifests sized from your targets
  • 119 semantic decorators; the runtime enforces 26 of them, including intent checks such as tReadOnly, tTenantIsolated and tIdempotent, plus circuit breakers, locks, caching and rate limits
  • Shared state across servers through the database you already have (@axiljs/stores), with no Redis required
  • A job queue that several servers can share, and migration safety checks before risky schema changes
  • AI governance: per-tenant budgets, PII redaction before prompts and recorded tests
  • Built-in API response handling
  • ORM Studio for visual API and database inspection, including a live Intent view
  • A CLI with 10 tested project templates and axil verify

Note

AxilJS requires Node.js 20+. TypeScript is installed per project by axil create. The current release is 0.3.6; all @axiljs/* packages share one version number.

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.

One ecosystem
HTTP + RoutingSecurity + ValidationAuth + RBACORM + MigrationsEvents + WebSocketsQueue + SchedulingResilience + ObservabilityAI + RAG + AgentsCloud + DeploymentMemory ManagementORM 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, from a single API to a cluster of workers on every core and many instances behind a load balancer. The templates give working starting points for each.

Where the name comes from

AxilJS is derived from SyntaxilitY:

Output
TXT
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.

PartMeaning
axilExtracted from SyntaxilitY; associated with agility and natural growth
itYSyntaxilitY signature
JSJavaScript

What is included?

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

PackagePurpose
@axiljs/coreHTTP server, router, middleware, SSE, static files, response manager
@axiljs/configEnvironment loading and typed configuration
@axiljs/securityHelmet, rate limiting (shared across cluster workers), CSRF, and sanitization
@axiljs/ormPostgreSQL, MySQL, and SQLite ORM with migrations and migration safety checks
@axiljs/storesSQL-backed shared state across servers: rate limits, idempotency, cache, locks, AI budgets
@axiljs/authJWT, password hashing, authentication, and RBAC
@axiljs/validationSchema-based request validation
@axiljs/testingTest runner, assertions, HTTP test client, and contract tests
@axiljs/eventsEvent bus and pub/sub, with broadcast to other worker processes
@axiljs/websocketRFC 6455 WebSocket server and rooms
@axiljs/queueJob queue, scheduling and retries; durable file storage or a SQL backend shared by several servers
@axiljs/circuitCircuit breaker, retry, and timeout utilities
@axiljs/observabilityLogging, metrics, tracing, and health checks
@axiljs/aiAI providers, RAG, agents, vector storage, MCP, and governance (budgets, redaction, recorded tests)
@axiljs/cloudMulti-tenancy, audit logs, feature flags, and deployment
@axiljs/memoryMemory monitoring, leak detection, GC, and optimization
@axiljs/pmExperimental package manager with lock files and checksums
@axiljs/studioBrowser-based developer dashboard (ORM Studio)
@axiljs/decorator119 semantic t-prefixed decorators that record intent as metadata
@axiljs/runtimeRuns decorator metadata: request context, intent verification, resilience and caching interceptors, audit, redaction
@axiljs/scaleCluster mode with an onPrimary hook, axil.scaling.json, capacity planning, load testing
@axiljs/cliProject templates, development server, tests, builds, capacity checks, deployment, and axil verify

A minimal AxilJS application

Create a project with the AxilJS CLI. On a terminal it asks for a name, then lets you pick one of 10 templates with the arrow keys (space to select):

Terminal
❯npx @axiljs/cli create my-api
❯cd my-api
❯npm run dev

create installs dependencies for you. Every template compiles under strict TypeScript and ships with its own passing tests (npm test). See Templates for what each one contains, or pass -t <id> to skip the picker.

The development server (axil run) starts the application, starts ORM Studio, and watches the source tree 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
TS
1import { Application, cors } from '@axiljs/core'
2import { loadEnv, defineConfig } from '@axiljs/config'
3import { helmet, rateLimit } from '@axiljs/security'
4
5loadEnv()
6
7const config = defineConfig({
8  PORT: { type: 'number', default: 3000 },
9  NODE_ENV: { type: 'string', default: 'development' }
10})
11
12const app = new Application({
13  server: { port: config.PORT }
14})
15
16app.use(helmet())
17app.use(cors({ origin: '*' }))
18app.use(rateLimit({ max: 100, windowMs: 60000 }))
19
20app.get('/health', (req, res) => {
21  res.success(
22    { uptime: process.uptime() },
23    'Healthy'
24  )
25})
26
27app.get('/users/:id', (req, res) => {
28  res.success(
29    { id: req.params.id },
30    'User fetched'
31  )
32})
33
34app.post('/users', (req, res) => {
35  res.created(
36    req.body,
37    'User created'
38  )
39})
40
41app.listen()

Common response methods include:

TypeScript
TS
1res.success(data, message)
2res.created(data, message)
3res.paginated(items, total, page, limit, message)
4
5res.badRequest(message)
6res.unauthorized(message)
7res.forbidden(message)
8res.notFound(message)
9res.conflict(message)
10res.validationError(message)
11
12res.serverError(message)
13res.tooManyRequests()
14res.serviceUnavailable()
TypeScript
TS
1res.HTTP_200_OK(users, 'Users fetched');
2
3res.HTTP_201_CREATED(user, 'User created');
4
5res.HTTP_400_BAD_REQUEST('Invalid request');
6
7res.HTTP_401_UNAUTHORIZED('Invalid token');
8
9res.HTTP_403_FORBIDDEN('Permission denied');
10
11res.HTTP_404_NOT_FOUND('User not found');
12
13res.HTTP_409_CONFLICT('Email already exists');
14
15res.HTTP_500_INTERNAL_SERVER_ERROR('Database error');
16
17res.HTTP_503_SERVICE_UNAVAILABLE('Service unavailable');
18
19res.HTTP_204_NO_CONTENT();
20
21res.HTTP_405_METHOD_NOT_ALLOWED();
22
23res.HTTP_406_NOT_ACCEPTABLE();
24
25res.HTTP_415_UNSUPPORTED_MEDIA_TYPE();
26
27res.HTTP_429_TOO_MANY_REQUESTS();
28
29res.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
TS
1import {
2  createConnection,
3  Entity,
4  Column,
5  PrimaryKey,
6  BaseRepository
7} from '@axiljs/orm'
8
9@Entity('users')
10class User {
11  @PrimaryKey()
12  id: number
13
14  @Column({ type: 'string', length: 255 })
15  name: string
16
17  @Column({ type: 'string', unique: true })
18  email: string
19}
20
21const db = await createConnection({
22  driver: 'postgres',
23  url: process.env.DATABASE_URL
24})
25
26class UserRepository extends BaseRepository<User> {
27  constructor() {
28    super(User, db)
29  }
30}
31
32const users = new UserRepository()
33
34const user = await users.create({
35  name: 'Tariq',
36  email: 'tariq@syntaxility.dev'
37})

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:

CapabilityDescription
API ExplorerDiscover routes and use the built-in Try It Out interface
Database BrowserInspect tables, columns, constraints, and paginated data
SQL Query EditorRun read-only SQL queries with syntax highlighting
Realtime MonitorInspect WebSocket connections and SSE streams
Collection ExportExport Postman, Insomnia, and OpenAPI collections
QR AccessOpen the application or Studio from another device on the same network

Studio also has a schema diagram of every table and foreign key, a command palette (Ctrl K), and light and dark themes. It supports SQLite, PostgreSQL, and MySQL, and only ever reads from your database.

Built for backend architectures

AxilJS is not tied to a single application architecture.

You can organize an application as:

MVC
modelsviewscontrollersroutes

or as a modular monolith:

Application
AuthUsersProductsOrdersPayments

or evolve toward distributed services:

API Gateway
AuthUsersOrders
Events
The gateway routes to independent services; Auth and Orders communicate through 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 test
❯axil build
❯axil capacity
❯axil deploy
❯axil doctor

During development, axil run watches the source tree, recompiles changed files, and restarts the app. axil capacity checks whether your machine or deployment can carry a target load, and axil deploy sizes its Kubernetes manifests from the same axil.scaling.json.

From HTTP to AI

AxilJS extends beyond the HTTP layer.

The ecosystem includes infrastructure for:

HTTP
Auth + RBACValidationORMEventsWebSocketsQueuesResilienceObservabilityAI / RAG / Agents / MCPCloud / Multi-tenancyMemory Management

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

TypeScript
TS
1import {
2  OpenAIProvider,
3  RAGPipeline,
4  VectorStore,
5  Agent,
6  calculatorTool
7} from '@axiljs/ai'
8
9const provider = new OpenAIProvider({
10  apiKey: process.env.OPENAI_API_KEY
11})
12
13const rag = new RAGPipeline({
14  provider,
15  vectorStore: new VectorStore()
16})
17
18const agent = new Agent({
19  provider,
20  tools: [calculatorTool],
21  maxIterations: 10
22})

Deployment

AxilJS can generate deployment artifacts through the CLI:

Terminal
❯axil deploy

The generated deployment structure can include:

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

With an axil.scaling.json in the project, the manifests are sized from it: replicas, an autoscaler, pod CPU and memory, and the worker count per pod. See Scale.

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.

Traditional approach: separate libraries, assembled and integrated by hand.

FrameworkORMAuth libraryValidation libraryQueueWebSocket libraryObservabilityAI SDKsCustom toolingDeployment scripts
Framework + ORM + Auth library + … + Deployment scripts, each chosen and wired together separately.

AxilJS: one coordinated ecosystem.

AxilJS
HTTPORMAuthValidationEventsWebSocketsQueueResilienceMetricsAICloudMemoryStudioCLI

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
  • Templates — Pick a working app to start from
  • 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
  • Runtime — Make your decorators run
  • Scale — Cluster mode and capacity planning
  • ORM Studio — Explore the visual development dashboard

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY