node-backend

Node.js Backend

Node runs your JavaScript on one thread with an event loop. It scales by never blocking that thread — every CPU-bound or sync call freezes all requests. The craft is async-correct code, streaming over buffering, and a clean process lifecycle.

Audit a package.json for engine pin, lockfile, and risky scripts: python3 scripts/check_package.py package.json

Never block the event loop

// Wrong — sync read blocks EVERY in-flight request until the file loads
import { readFileSync } from "node:fs";
app.get("/data", (req, res) => res.send(readFileSync("big.json")));

// Correct — async yields the loop while I/O happens
import { readFile } from "node:fs/promises";
app.get("/data", async (req, res) => res.send(await readFile("big.json")));

*Sync calls, JSON.parse of a huge string, a tight for over a million items, synchronous crypto/zlib — all freeze the loop and tank p99 for every concurrent request. For genuine CPU work (image resize, hashing), offload to a Worker Thread or a separate service; don't compute it inline. Detail → references/event-loop.md.

Async errors must be caught — or the process dies

// Wrong — a rejected promise in a handler with no catch → unhandledRejection
app.get("/x", async (req, res) => { const u = await db.get(); res.json(u); });
// (if db.get rejects, Express 4 doesn't catch async throws → hangs or crashes)

// Correct — wrap, or use a framework that awaits handlers (Express 5 / Fastify do)
app.get("/x", async (req, res, next) => {
  try { res.json(await db.get()); } catch (e) { next(e); }
});

In Express 4 an async handler that throws is not caught by the error middleware — you need a wrapper (express-async-errors) or per-handler try/catch. Express 5 and Fastify await handlers natively. Always register a top-level process.on("unhandledRejection") + uncaughtException that logs and exits — a silent rejection corrupts state.

Stream large payloads, don't buffer