Scale

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.

5 min readUpdated DocumentationEdit this page
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.

❯npm install @axiljs/scale
❯pnpm add @axiljs/scale
❯yarn add @axiljs/scale
❯bun add @axiljs/scale

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/core worker 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:

DirectionWhat it meansHow AxilJS does it
VerticalUse every core of a machine: one worker process per coreserve() forks workers with node:cluster
HorizontalRun more machines (VMs, pods) behind a load balancerhorizontal.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:

Output
TXT
instance rps   = rpsPerWorker × min(workers, cpus) × clusterEfficiency
required rps   = target.rps × (1 + headroom)
instances      = ceil(required rps ÷ instance rps)
instance mem   = workers × memoryPerWorkerMb + connections × memoryPerConnectionKb
  • rpsPerWorker is measured: either a hello-world calibration on your machine (the framework ceiling) or a load test against your real route.
  • clusterEfficiency (default 0.85) accounts for workers not scaling perfectly linearly. It applies only when there is more than one worker.
  • headroom (default 0.3) is spare capacity above the target, for spikes, deploys and losing an instance.
  • memoryPerConnectionKb defaults to 48 per 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:

Output
TXT
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)  =        17

So 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

AreaAPIPage
Configurationaxil.scaling.json, resolveScaling(), loadScalingConfig(), defineScaling(), AXIL_WORKERSConfiguration
Running on every coreserve(): worker per core, crash restart with backoff, graceful drain, per-worker memory and connection limitsCluster
Capacity planningdetectSystem(), calibrate(), loadTest(), planCapacity(), hostChecks()Capacity planning
Multi-process readinessscanSource(), scanProject()Readiness

The CLI builds on the same API:

  • axil capacity calibrates or load-tests, plans, runs host checks and the readiness scan. See axil capacity.
  • axil capacity --init writes a starter axil.scaling.json.
  • axil deploy reads axil.scaling.json: replicas from instances.min, an autoscaler up to instances.max, pod resources from instanceSize, AXIL_WORKERS pinned to the pod's CPUs, and a termination grace period that covers the drain.

Quick start

main.ts
TS
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 })
axil.scaling.json
JSON
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}
Terminal
❯axil capacity # does this config carry 50k req/s?

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

Terminal
❯axil create my-api --template high-scale-api

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?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY