Introduction
What AxilJS is, the 22 @axiljs packages it ships, its 10 project templates, and how it fits a modern TypeScript backend.
On this page17
- Why AxilJS?
- The AxilJS philosophy
- One ecosystem
- Production-oriented defaults
- Grow without replacing the foundation
- Where the name comes from
- What is included?
- A minimal AxilJS application
- A simple API
- ORM and database support
- ORM Studio
- Built for backend architectures
- Development workflow
- From HTTP to AI
- Deployment
- What makes AxilJS different?
- Next steps
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,tTenantIsolatedandtIdempotent, 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.
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:
Synt + axil + itY + JS
────
agility through syntax
natural point of growth
SyntaxilitY signatureThe 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 (shared across cluster workers), CSRF, and sanitization |
@axiljs/orm | PostgreSQL, MySQL, and SQLite ORM with migrations and migration safety checks |
@axiljs/stores | SQL-backed shared state across servers: rate limits, idempotency, cache, locks, AI budgets |
@axiljs/auth | JWT, password hashing, authentication, and RBAC |
@axiljs/validation | Schema-based request validation |
@axiljs/testing | Test runner, assertions, HTTP test client, and contract tests |
@axiljs/events | Event bus and pub/sub, with broadcast to other worker processes |
@axiljs/websocket | RFC 6455 WebSocket server and rooms |
@axiljs/queue | Job queue, scheduling and retries; durable file storage or a SQL backend shared by several servers |
@axiljs/circuit | Circuit breaker, retry, and timeout utilities |
@axiljs/observability | Logging, metrics, tracing, and health checks |
@axiljs/ai | AI providers, RAG, agents, vector storage, MCP, and governance (budgets, redaction, recorded tests) |
@axiljs/cloud | Multi-tenancy, audit logs, feature flags, and deployment |
@axiljs/memory | Memory monitoring, leak detection, GC, and optimization |
@axiljs/pm | Experimental package manager with lock files and checksums |
@axiljs/studio | Browser-based developer dashboard (ORM Studio) |
@axiljs/decorator | 119 semantic t-prefixed decorators that record intent as metadata |
@axiljs/runtime | Runs decorator metadata: request context, intent verification, resilience and caching interceptors, audit, redaction |
@axiljs/scale | Cluster mode with an onPrimary hook, axil.scaling.json, capacity planning, load testing |
@axiljs/cli | Project 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):
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.
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:
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()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:
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:
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 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:
or as a modular monolith:
or evolve toward distributed services:
The framework provides the backend capabilities; the application architecture remains yours to choose.
Development workflow
The AxilJS CLI provides the main development lifecycle:
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:
For AI applications, @axiljs/ai provides provider integrations, RAG pipelines, vector storage, agents, and tools.
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:
The generated deployment structure can include:
deploy/
├── Dockerfile
├── deployment.yaml
└── deploy.shWith 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.
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.
AxilJS: one coordinated ecosystem.
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
axilcommand-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?