Node Microservice

Node.js Microservice

Overview

A Node service is six things: config, an HTTP surface, state (DB + cache), async work, outbound calls, and operability. Node's specific hazards are that one synchronous line blocks every concurrent request (single-threaded event loop), and that fetch() has no default timeout — so a hung dependency leaks handles until the process dies.

Verified against the npm registry and nodejs.org, 2026-08-01 — registry facts, not blog claims: Node 24.18.1 "Krypton" LTS (26.5.1 is current non-LTS; 22 "Jod" in maintenance) · TypeScript 7.0.2 · Fastify 5.11.0 · Express 5.2.1 · NestJS 11.1.28 · Hono 4.12.33 · Prisma 7.9.1 · Drizzle 0.45.2 · pino 10.3.1 · BullMQ 6.0.5 · undici 8.9.0 · Zod 4.4.3 · Vitest 4.1.10.

When to Use

• Starting a Node/TS service, or adding a route/worker to one
• Choosing a framework, ORM, cache, queue, or test runner
• Reviewing Node service code for production-readiness
• Diagnosing: event-loop blocking, memory growth, OOMKills, pool exhaustion in serverless, unhandled rejections crashing the process, ESM/CJS interop errors
• Containerising a Node service (including the PID-1 signal problem)

Not for: browser/React work (see web-frontend), or CLI tools.

Step 0: Choose the framework

Fastify's real differentiator is JSON-schema serialisation — it compiles a serialiser from your response schema, which is both faster than JSON.stringify and prevents accidentally leaking fields you didn't declare. That second property is a security feature. Full comparison in references/frameworks.md.

Quick Reference

Bootstrap a new service

myservice/
  package.json               # "type": "module", engines.node pinned
  src/
    index.ts                 # bootstrap + graceful shutdown only
    config.ts                # Zod-validated env, parsed at import
    server.ts                # framework wiring, routes, error handler
    routes/
    services/                # business logic — no HTTP or SQL types
    repositories/            # DB access
    clients/                 # outbound HTTP
  test/
  Dockerfile

1. "type": "module" and engines.node: ">=24". Decide ESM once — the mixed state is the top source of "works locally, breaks in CI".
2. Zod-parse process.env at import so a missing var crashes at boot, not on the first request that needs it.
3. One undici Agent and one DB pool, created once and injected.
4. AsyncLocalStorage for the request ID; pino child logger bound to it.
5. /healthz (liveness, process-local) and /readyz (readiness, checks deps).
6. Graceful shutdown: fail readiness → LB propagation delay → server.close() → drain → close pools.
7. --init (or dumb-init) in the container, because Node as PID 1 doesn't reap zombies and mishandles signals.

The non-negotiables

1. Every fetch/undici call has a timeout. fetch() has none by default. Use AbortSignal.timeout(ms). In real codebases this is the most-violated rule — one audit found 45 fetch calls and a single AbortController.
2. Never block the event loop. No sync crypto, no sync fs in a request path, no CPU-bound loops. Offload to worker_threads.
3. Config validated at boot. Fail fast.
4. One client per process, created at startup — never per request. A per-request client discards connection pooling entirely.
5. AsyncLocalStorage for request context. A module-level variable does not survive await — it will silently serve one request's ID to another.
6. Handle unhandledRejection. Modern Node crashes the process by default. Know whether you want that (usually yes — but log it first).
7. --max-old-space-size below the container limit. V8 otherwise sizes the heap from the host and gets OOMKilled.
8. --init in the container. Node as PID 1 leaves zombies and mishandles SIGTERM.
9. Idempotent queue consumers. BullMQ retries; at-least-once is what you get.
10. Liveness must not check dependencies. One DB blip otherwise restarts every pod and turns a blip into an outage.

Reference Map

Common Mistakes