Node.js Backend Expert
The boundary is hostile: validate input, handle every rejection, and never trust the client. Keep handlers thin, push logic into services, and make the process production-safe (timeouts, health, graceful shutdown).
When to Use
- Building/structuring an HTTP API or service in Node (Express, Fastify, Hono…).
- Routing, middleware, input validation, auth, sessions, rate limiting.
- Unhandled-rejection, error-propagation, streaming, or backpressure issues.
- Project layout: transport → service → data layer.
When NOT to Use
- Next.js server features (RSC, server actions) →
nextjs-expert.
- SQL/schema/indexing →
sql-expert. API contract design → api-design-expert.
- Deep auth threat modeling/OWASP →
security-expert.
Core Principles
1. Layering
- Handlers/controllers stay thin (parse → call service → format response). Business logic lives in services; data access is isolated and mockable.
- Load config from env, validated at startup (
zod/envalid); fail fast on missing/invalid config. No process.env.X scattered through code.
2. Async & error discipline
async/await throughout. Every route's thrown error must reach a central error handler — wrap async handlers (or use Fastify/Express 5 which await handlers natively).
- Attach
process.on("unhandledRejection")/"uncaughtException" to log and exit; don't swallow.
- Validate request body/query/params at the edge with a schema; reject early with 400 and a structured error.
3. Security baseline
helmet for headers, explicit CORS allowlist, rate limiting on public/auth routes.
- Hash passwords with
argon2/bcrypt; sign tokens/sessions with env secrets; cookies HttpOnly+Secure+SameSite. Never log secrets, tokens, or full request bodies with PII.
- Parameterize all DB access (no string-built SQL); cap body size.
4. Production-ready process
/health (liveness) + readiness; graceful shutdown on SIGTERM (stop accepting, drain in-flight, close DB pool).
- Set server/socket timeouts. Stream large responses/uploads instead of buffering. Structured logging (
pino) with request IDs.
Decision Guide
| Need |
Reach for |
| Max performance / schema-first |
Fastify |
| Minimal/edge/runtime-agnostic |
Hono |
| Ubiquitous ecosystem / familiarity |
Express (use v5 for async error handling) |
| Input validation |
zod / valibot at the boundary |
| Heavy CPU work |
worker_threads / separate service (don't block the event loop) |
Common Mistakes
- Blocking the event loop (sync crypto/
fs, big JSON, CPU loops) → stalls all requests; offload to workers/streams.
- Unhandled async errors in Express 4 (thrown in a promise) → use a wrapper or Express 5.
- Trusting client input (mass assignment, unvalidated query) → validate + allowlist fields.
- Catch-and-ignore (
catch (e) {}) → log with context and respond appropriately.
- No timeouts / no shutdown → hung sockets and dropped requests on deploy.
- Secrets in code or logs → env + secret manager; redact logs.
Examples
Central async error handling + validation (Express 5)
import express from "express";
import { z } from "zod";
const app = express();
app.use(express.json({ limit: "1mb" }));
const Body = z.object({ email: z.string().email(), name: z.string().min(1) });
app.post("/users", async (req, res) => { // Express 5 awaits handlers
const body = Body.parse(req.body); // throws -> error middleware
const user = await userService.create(body);
res.status(201).json(user);
});
app.use((err, _req, res, _next) => {
const status = err?.name === "ZodError" ? 400 : 500;
if (status === 500) logger.error({ err }, "unhandled");
res.status(status).json({ error: { message: err.message } });
});
Graceful shutdown
const server = app.listen(3000);
for (const sig of ["SIGTERM", "SIGINT"]) {
process.on(sig, () => server.close(() => db.end().then(() => process.exit(0))));
}
See Also
api-design-expert — endpoint contracts, versioning, pagination.
sql-expert — the data layer behind services.
security-expert — authn/authz and OWASP hardening.
docker-expert / kubernetes-expert — packaging and running the service.
1---2name: nodejs-backend-expert3description: "Expert Node.js backends (Express/Fastify/Hono): routing, middleware, validation, auth, async, and production hardening. Trigger keywords: Node.js, Express, Fastify, Hono, REST, middleware, JWT, session, zod, async, streams, unhandled rejection, graceful shutdown, backend, server. Use for building HTTP services, structuring backends, or fixing async/error/security issues."4metadata:5 source: https://skillmd.com/skills/miaoge-ge/nodejs-backend-expert6---78# Node.js Backend Expert910> The boundary is hostile: validate input, handle every rejection, and never trust the client. Keep handlers thin, push logic into services, and make the process production-safe (timeouts, health, graceful shutdown).1112## When to Use13- Building/structuring an HTTP API or service in Node (Express, Fastify, Hono…).14- Routing, middleware, input validation, auth, sessions, rate limiting.15- Unhandled-rejection, error-propagation, streaming, or backpressure issues.16- Project layout: transport → service → data layer.1718## When NOT to Use19- Next.js server features (RSC, server actions) → `nextjs-expert`.20- SQL/schema/indexing → `sql-expert`. API contract design → `api-design-expert`.21- Deep auth threat modeling/OWASP → `security-expert`.2223## Core Principles2425### 1. Layering26- Handlers/controllers stay thin (parse → call service → format response). Business logic lives in services; data access is isolated and mockable.27- Load config from env, **validated at startup** (`zod`/`envalid`); fail fast on missing/invalid config. No `process.env.X` scattered through code.2829### 2. Async & error discipline30- `async/await` throughout. Every route's thrown error must reach a **central error handler** — wrap async handlers (or use Fastify/Express 5 which await handlers natively).31- Attach `process.on("unhandledRejection")`/`"uncaughtException"` to log and exit; don't swallow.32- Validate request body/query/params at the edge with a schema; reject early with 400 and a structured error.3334### 3. Security baseline35- `helmet` for headers, explicit CORS allowlist, rate limiting on public/auth routes.36- Hash passwords with `argon2`/`bcrypt`; sign tokens/sessions with env secrets; cookies `HttpOnly`+`Secure`+`SameSite`. Never log secrets, tokens, or full request bodies with PII.37- Parameterize all DB access (no string-built SQL); cap body size.3839### 4. Production-ready process40- `/health` (liveness) + readiness; **graceful shutdown** on `SIGTERM` (stop accepting, drain in-flight, close DB pool).41- Set server/socket timeouts. **Stream** large responses/uploads instead of buffering. Structured logging (`pino`) with request IDs.4243## Decision Guide44| Need | Reach for |45|------|-----------|46| Max performance / schema-first | Fastify |47| Minimal/edge/runtime-agnostic | Hono |48| Ubiquitous ecosystem / familiarity | Express (use v5 for async error handling) |49| Input validation | `zod` / `valibot` at the boundary |50| Heavy CPU work | worker_threads / separate service (don't block the event loop) |5152## Common Mistakes53- **Blocking the event loop** (sync crypto/`fs`, big JSON, CPU loops) → stalls all requests; offload to workers/streams.54- **Unhandled async errors** in Express 4 (thrown in a promise) → use a wrapper or Express 5.55- **Trusting client input** (mass assignment, unvalidated query) → validate + allowlist fields.56- **Catch-and-ignore** (`catch (e) {}`) → log with context and respond appropriately.57- **No timeouts / no shutdown** → hung sockets and dropped requests on deploy.58- **Secrets in code or logs** → env + secret manager; redact logs.5960## Examples6162**Central async error handling + validation (Express 5)**63```js64import express from "express";65import { z } from "zod";6667const app = express();68app.use(express.json({ limit: "1mb" }));6970const Body = z.object({ email: z.string().email(), name: z.string().min(1) });7172app.post("/users", async (req, res) => { // Express 5 awaits handlers73 const body = Body.parse(req.body); // throws -> error middleware74 const user = await userService.create(body);75 res.status(201).json(user);76});7778app.use((err, _req, res, _next) => {79 const status = err?.name === "ZodError" ? 400 : 500;80 if (status === 500) logger.error({ err }, "unhandled");81 res.status(status).json({ error: { message: err.message } });82});83```8485**Graceful shutdown**86```js87const server = app.listen(3000);88for (const sig of ["SIGTERM", "SIGINT"]) {89 process.on(sig, () => server.close(() => db.end().then(() => process.exit(0))));90}91```9293## See Also94- `api-design-expert` — endpoint contracts, versioning, pagination.95- `sql-expert` — the data layer behind services.96- `security-expert` — authn/authz and OWASP hardening.97- `docker-expert` / `kubernetes-expert` — packaging and running the service.