Scaling
How AxilJS apps scale honestly: one worker per core, many instances behind a load balancer, and @axiljs/scale to size, run and check the deployment.
On this page8
@axiljs/scale gives an AxilJS app three things: a cluster supervisor that runs it on every core, a capacity planner that tells you how many machines a target needs, and a static scan for code that breaks once more than one process runs. It has zero dependencies and uses only Node.js built-ins.
The honest numbers
No Node.js framework, or framework in any other language, serves millions of requests per second from one process or one machine.
- One
@axiljs/coreworker handles roughly 15,000 to 25,000 req/s on a hello-world route. Real routes that validate input, check auth and call a database do less. - A Node.js process runs JavaScript on one core. A second core does nothing for it.
Large targets are reached the same way everywhere:
| Direction | What it means | How AxilJS does it |
|---|---|---|
| Vertical | Use every core of a machine: one worker process per core | serve() forks workers with node:cluster |
| Horizontal | Run more machines (VMs, pods) behind a load balancer | horizontal.instances in axil.scaling.json, sized by axil capacity, deployed by axil deploy |
The maths
The planner uses a deliberately simple model, printed in every report so you can check it:
instance rps = rpsPerWorker × min(workers, cpus) × clusterEfficiency
required rps = target.rps × (1 + headroom)
instances = ceil(required rps ÷ instance rps)
instance mem = workers × memoryPerWorkerMb + connections × memoryPerConnectionKbrpsPerWorkeris measured: either a hello-world calibration on your machine (the framework ceiling) or a load test against your real route.clusterEfficiency(default0.85) accounts for workers not scaling perfectly linearly. It applies only when there is more than one worker.headroom(default0.3) is spare capacity above the target, for spikes, deploys and losing an instance.memoryPerConnectionKbdefaults to48per open keep-alive connection. WebSockets cost more.- Usable instance memory is taken as 85% of
instanceSize.memoryGb, leaving room for the OS.
Worked example: 1.5 million req/s
Target 1,500,000 req/s, 30% headroom, a measured 17,000 req/s per worker, 8-CPU instances:
required rps = 1,500,000 × 1.3 = 1,950,000
instance rps = 17,000 × 8 × 0.85 = 115,600
instances = ceil(1,950,000 ÷ 115,600) = 17So the deployment needs 17 instances of 8 CPUs at peak, and horizontal.instances.max must be at least 17. axil capacity does this arithmetic with your numbers and fails the check if max is too low.
Note
Both clusterEfficiency and memoryPerConnectionKb can be overridden in planCapacity() when you have better numbers. Always confirm the plan with a load test against a real deployment.
What the package gives you
| Area | API | Page |
|---|---|---|
| Configuration | axil.scaling.json, resolveScaling(), loadScalingConfig(), defineScaling(), AXIL_WORKERS | Configuration |
| Running on every core | serve(): worker per core, crash restart with backoff, graceful drain, per-worker memory and connection limits | Cluster |
| Capacity planning | detectSystem(), calibrate(), loadTest(), planCapacity(), hostChecks() | Capacity planning |
| Multi-process readiness | scanSource(), scanProject() | Readiness |
The CLI builds on the same API:
axil capacitycalibrates or load-tests, plans, runs host checks and the readiness scan. Seeaxil capacity.axil capacity --initwrites a starteraxil.scaling.json.axil deployreadsaxil.scaling.json: replicas frominstances.min, an autoscaler up toinstances.max, pod resources frominstanceSize,AXIL_WORKERSpinned to the pod's CPUs, and a termination grace period that covers the drain.
Quick start
1import { Application } from '@axiljs/core'
2import { serve } from '@axiljs/scale'
3
4serve(() => {
5 const app = new Application()
6 app.get('/', (_req, res) => res.success({ ok: true, pid: process.pid }))
7 return app
8}, { port: 3000 })1{
2 "target": { "rps": 50000, "concurrentConnections": 100000, "p99Ms": 50 },
3 "vertical": { "workers": "auto", "maxConnectionsPerWorker": 10000, "memoryPerWorkerMb": 512,
4 "shutdownTimeoutMs": 10000, "keepAliveTimeoutMs": 65000 },
5 "horizontal": { "instances": { "min": 3, "max": 10 }, "instanceSize": { "cpus": 4, "memoryGb": 8 } },
6 "headroom": 0.3
7}With workers: "auto", serve() starts one worker per core. Set AXIL_WORKERS=1 in development to run a single process.
What breaks with more than one process
Every worker and every instance has its own memory. Anything kept in memory splits: rate limits multiply, cron jobs fire once per worker, WebSocket broadcasts miss clients on other workers, SQLite cannot be shared. The readiness scan finds these in your src/ and says how to fix each one.
Per-request features (the request context, retries, timeouts, redaction) need nothing shared and work unchanged.
Complete example
The high-scale-api template wires serve(), axil.scaling.json, axil capacity, axil deploy and @axiljs/runtime together, with tests that build the app in one process and never fork the cluster.
Next steps
Was this page helpful?