# Miaoge Ge Coding Agent Skills Nodejs Backend Expert

> Node.js Backend Expert

- Skill: `tomevault-io/miaoge-ge-coding-agent-skills-nodejs-backend-expert` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/miaoge-ge-coding-agent-skills-nodejs-backend-expert`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/miaoge-ge-coding-agent-skills-nodejs-backend-expert/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/miaoge-ge-coding-agent-skills-nodejs-backend-expert

---


# 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)**
```js
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**
```js
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.

---
> Source: [Miaoge-Ge/coding-agent-skills](https://github.com/Miaoge-Ge/coding-agent-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-15 -->