Node.js Backend

intent

build production-grade Node.js backends with clean layered architecture, type safety, validation at boundaries, centralized error handling, and resilience patterns. use this skill when designing REST APIs, Express/Fastify/Hono/NestJS/Koa servers, tRPC procedures, serverless functions, or any server-side TypeScript code. applies to new builds and refactoring legacy backends.

inputs

• deployment target: edge/serverless (Cloudflare Workers, Lambda), performance-critical API, enterprise team, or legacy ecosystem
• framework experience: team comfort with Express, Fastify, NestJS, Hono, or other runtimes
• existing codebase: monorepo layout, current architecture, shared schemas
• TypeScript version: 5.0+ recommended for performance and type inference (const type parameters, const assertions)
• external services: third-party APIs, databases, cache layers (Redis), message queues
• documentation source: before implementing framework-specific APIs (Express 5, Fastify 5, Node.js 22+ built-ins), verify current docs via query-docs context because training data may lag releases
• env vars required: parse and validate startup (DATABASE_URL, REDIS_URL, JWT_SECRET, LOG_LEVEL, NODE_ENV, PORT)

procedure

1. select framework by deployment context and team constraints

deployment	framework	tradeoff
edge/serverless	Hono	zero dependencies, fastest cold starts, minimal bundle
performance API	Fastify	higher throughput than Express, built-in schema validation, lower latency
enterprise/structured	NestJS	dependency injection, decorator conventions, team discipline, learning curve
legacy/ecosystem	Express	widest middleware ecosystem, longest history, slowest throughput
lightweight	Koa	minimal core, composable middleware, smaller than Express

input: ask user for deployment target, cold start budget, team experience, constraints in existing codebase.

output: chosen framework name, rationale documented in project README.

2. design layered directory structure (clean architecture)

create this folder layout:

src/
├── routes/          # HTTP handlers only: parse request, call service, format response
├── middleware/      # Auth, validation, rate limiting, logging, error catching
├── services/        # Business logic, orchestration (zero HTTP types here)
├── repositories/    # Data access, queries, ORM calls (no HTTP errors)
├── types/           # Shared TypeScript interfaces, constants, enums
├── config/          # Environment, connection pools, global setup
└── errors/          # Custom error classes (AppError subclasses)

enforce dependency direction: routes -> services -> repositories. never import upward (repositories importing routes is a code smell).

input: folder structure plan, existing layout constraints.

output: directory tree created, verified with find src -type d | sort.

3. enforce TypeScript strictness and type inference

input: tsconfig.json.

set compiler options:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "noImplicitThis": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "skipLibCheck": true,
    "moduleResolution": "bundler"
  }
}

rules:

• use import type { } for type-only imports (zero runtime cost).
• prefer interface for object shapes (faster type resolution than intersection types).
• use unknown instead of any -- forces explicit type narrowing.
• extract types from schemas via z.infer<typeof schema> (single source of truth).
• minimize as type assertions; use type guards and conditionals instead.
• add explicit return types to all exported functions (faster declaration emit, clearer contracts).
• untyped third-party package? add declare module 'pkg' { ... } in types/ambient.d.ts.

output: tsc --noEmit passes with zero errors and warnings.

4. define request/response schemas at boundary entry points

use Zod (TypeScript inference first) or TypeBox (Fastify native, better performance). validate only at boundaries: HTTP request entry, before database mutations, environment vars at startup.

example (Express + Zod):

import { z } from 'zod';
export const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1),
});
export type CreateUserInput = z.infer<typeof createUserSchema>;

app.post('/users', (req, res, next) => {
  try {
    const payload = createUserSchema.parse(req.body);
    const user = await userService.create(payload);
    res.status(201).json({ data: user });
  } catch (err) {
    next(err);
  }
});

compose schemas with .extend(), .pick(), .omit(), .partial(), .merge() to avoid duplication.

input: request body shape, query params, path params, response shape.

output: validated payload, strict type inference (CreateUserInput matches schema exactly).

5. build custom error hierarchy for consistent error responses

create base class in errors/AppError.ts:

export class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number = 500,
    public isOperational: boolean = true,
    public details?: unknown
  ) {
    super(message);
    Object.setPrototypeOf(this, AppError.prototype);
  }
}

export class ValidationError extends AppError {
  constructor(message: string, details?: unknown) {
    super(message, 400, true, details);
  }
}

export class NotFoundError extends AppError {
  constructor(message: string) {
    super(message, 404, true);
  }
}

export class UnauthorizedError extends AppError {
  constructor(message: string = 'Unauthorized') {
    super(message, 401, true);
  }
}

export class ForbiddenError extends AppError {
  constructor(message: string = 'Forbidden') {
    super(message, 403, true);
  }
}

export class ConflictError extends AppError {
  constructor(message: string) {
    super(message, 409, true);
  }
}

output: error classes available for import in services and repositories.

6. wire centralized error handler middleware

place at the end of middleware stack:

// Express
app.use((err: unknown, req: Request, res: Response, next: NextFunction) => {
  if (err instanceof AppError) {
    return res.status(err.statusCode).json({
      error: {
        code: err.statusCode,
        message: err.message,
        ...(err.details && { details: err.details }),
      },
    });
  }

  // Unknown error: log full stack, return generic 500
  console.error('Unhandled error:', err);
  if (process.env.NODE_ENV === 'production') {
    return res.status(500).json({
      error: {
        code: 500,
        message: 'Internal server error',
      },
    });
  }

  res.status(500).json({
    error: {
      code: 500,
      message: err instanceof Error ? err.message : String(err),
      stack: err instanceof Error ? err.stack : undefined,
    },
  });
});

wrap async route handlers to auto-catch:

const asyncHandler = (fn: any) => (req: Request, res: Response, next: NextFunction) =>
  Promise.resolve(fn(req, res, next)).catch(next);

app.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await userService.findById(req.params.id);
  if (!user) throw new NotFoundError('User not found');
  res.json({ data: user });
}));

output: all errors caught, logged, and returned with consistent { error: { code, message, details? } } envelope.

7. design API routes following RESTful contract-first patterns

input: resource names, operations, response shapes.

before writing handler code, define route schema (Zod, Fastify JSON Schema, or OpenAPI spec):

export const listUsersSchema = {
  query: z.object({
    page: z.coerce.number().int().min(1).default(1),
    limit: z.coerce.number().int().min(1).max(100).default(20),
    status: z.enum(['active', 'inactive']).optional(),
    sort: z.string().optional(), // 'createdAt,desc'
  }),
  response: z.object({
    data: z.array(userResponseSchema),
    pagination: z.object({
      page: z.number(),
      limit: z.number(),
      total: z.number(),
      totalPages: z.number(),
    }),
  }),
};

follow conventions:

• resources: plural nouns /users, /orders, /posts.
• nesting: max 2 levels /users/:userId/orders/:orderId.
• methods: GET (read), POST (create), PUT (replace entire), PATCH (partial update), DELETE (remove).
• status codes: 200 (success), 201 (created, include Location header), 204 (no content on DELETE), 400 (bad input), 401 (no auth), 403 (forbidden), 404 (not found), 409 (conflict), 422 (business rule violation), 429 (rate limited), 500 (server fault).
• response envelope: { data, pagination?: { page, limit, total, totalPages } }.
• queries: ?page=1&limit=20&status=active&sort=createdAt,desc.
• versioning: URL path /api/v1/resource.

never return raw ORM objects or untyped data from handlers; serialize through a Zod schema to enforce Hyrum's Law (all observable fields become caller dependencies):

const userResponseSchema = z.object({
  id: z.string(),
  email: z.string(),
  name: z.string(),
  createdAt: z.string().datetime(),
  // omit password, internal fields
});

app.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await userService.findById(req.params.id);
  if (!user) throw new NotFoundError('User not found');
  const serialized = userResponseSchema.parse(user);
  res.json({ data: serialized });
}));

output: routes defined in routes/ with explicit schemas, handlers delegating to services, response validation.

8. implement validation at boundaries only

validate:

1. request entry: body (Zod), query params, path params, headers (auth).
2. before DB ops: ensure constraints, unique checks, business rules at service layer (not in repository).
3. startup: environment variables with fail-fast (crash if missing).

do NOT validate inside repositories or services (already validated at boundary).

example:

// config/env.ts
const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().default(3000),
});

export const env = envSchema.parse(process.env);
if (!env) throw new Error('Invalid environment');

output: validated payloads at routes, services assume valid input, env crash on startup if invalid.

9. implement async patterns for sequential, parallel, and timeout scenarios

pattern	use case	example
async/await	sequential operations	fetch user, then fetch orders
Promise.all()	parallel independent tasks	fetch user + fetch posts + fetch comments in parallel
Promise.allSettled()	parallel, some may fail	call 3 external APIs, ignore failures
Promise.race()	timeout or first-wins	fetch from cache, race against DB query, timeout if >1s

never use sync methods in production (readFileSync, execSync, require() dynamic modules). use fs.promises, streams, or worker threads instead.

offload CPU-bound work to worker threads (Piscina or Node.js Worker API).

input: operation type, dependencies, timeout budget.

output: non-blocking code, event loop not blocked.

10. set up production resilience: health, caching, load shedding, circuit breakers

fail-fast environment validation (step 8 above): parse env vars at startup, crash if invalid.

health endpoints:

// shallow health (process alive?)
app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

// deep readiness (dependencies reachable?)
app.get('/ready', asyncHandler(async (req, res) => {
  await db.query('SELECT 1');
  await redis.ping();
  res.json({ status: 'ready' });
}));

load balancers use /ready for traffic routing; monitoring probes /health for liveness. don't conflate them.

caching:

• Redis cache-aside for DB queries and external API responses (check cache, miss -> query, store result, TTL).
• in-memory LRU with TTL for hot paths (user preferences, feature flags).
• always invalidate on writes (mutations clear cache keys).

load shedding (Fastify example):

import underPressure from '@fastify/under-pressure';
fastify.register(underPressure, {
  maxEventLoopDelay: 1000,
  maxHeapUsedBytes: 1024 * 1024 * 1024,
  maxRssBytes: 2 * 1024 * 1024 * 1024,
});
// returns 503 when thresholds exceeded

response schemas (Fastify):

fastify.post('/users', {
  schema: {
    response: {
      201: {
        type: 'object',
        properties: {
          data: { $ref: '#/definitions/User' },
        },
      },
    },
  },
  handler: async (req, res) => { ... }
});

enables fast-json-stringify for 2-3x faster serialization.

circuit breaker (external service calls):

import CircuitBreaker from 'opossum';

const breaker = new CircuitBreaker(async (url: string) => {
  return fetch(url).then(r => r.json());
}, {
  timeout: 3000,
  errorThresholdPercentage: 50,
  resetTimeout: 30000,
});

breaker.fallback(() => cachedResponse || defaultValue);
const data = await breaker.fire('https://api.example.com/data');

states: CLOSED (normal) -> OPEN (failing, return fallback) -> HALF_OPEN (test probe). prevents cascade failures.

output: /health and /ready endpoints responding, caching layer operational, load shedding active, circuit breakers protecting external calls.

11. validate third-party API responses before use

never trust external service responses. parse through a Zod schema:

const externalUserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email().optional(),
  // omit unknown fields
});

const externalUser = await fetch('https://api.external.com/user/123')
  .then(r => r.json());

const validated = externalUserSchema.parse(externalUser);

prevents injection, type confusion, and crashes from misbehaving upstream services.

output: validated data, type-safe usage downstream.

12. verify and test before declaring complete

run before commit:

tsc --noEmit                    # zero TypeScript errors
npm test                        # all tests passing
npm run lint                    # no style violations
npm run type-check              # strict type safety

do NOT commit code with as any, @ts-ignore, or non-null assertions on untrusted data. treat TypeScript bypasses as design smells; find the typed solution instead.

output: all checks passing, zero warnings, code ready for review.

decision points

1. framework choice: if deployment is edge/serverless (Cloudflare Workers, Lambda), choose Hono for minimal cold start. else if team prioritizes API throughput and built-in validation, choose Fastify. else if enterprise structure and DI patterns required, choose NestJS. else choose Express (widest ecosystem, longest history).

2. schema validation library: if using Fastify, TypeBox is native and faster. else if TypeScript inference and developer experience matter, choose Zod. else use built-in JSON.parse with manual type guards (slower, not recommended).

3. error handling strategy: if API has existing error envelope format, match it exactly (consistency for callers). else implement custom AppError hierarchy with subclasses for 400, 401, 403, 404, 409, 422, 429. never return different error shapes from different endpoints.

**4. response serial