ExpressAdapter

Kind: Class

Source: packages/platform-express/adapters/express-adapter.ts

Part of: Platform Express

ExpressAdapter connects the platform-agnostic HTTP adapter contract to an Express application. It manages request and response hooks, response helpers, rendering and redirects, and Express-level error or not-found handlers.

Extends: AbstractHttpAdapter

Methods

Where it refuses work

• ExpressAdapter stops the work with InternalServerErrorException when !next — “HTTP adapter does not support filtering on version”.
• ExpressAdapter stops the work with an early return when version.includes(VERSION_NEUTRAL), in 2 places.
• ExpressAdapter stops the work with an early return when isNil(body).
• ExpressAdapter stops the work with an early return when !this.httpServer.
• ExpressAdapter stops the work with an early return when options && options.prefix.
• ExpressAdapter stops the work with an early return when Array.isArray(extractedVersion) && version.filter(v => extractedVersion.includes(v as str….

When something fails

• ExpressAdapter handles failure in 2 places: it lets it reach the caller in all 2.

Diagram

mermaid
graph LR
  Client[HTTP Client] --> Express[Express Application]
  Express --> Adapter[ExpressAdapter]
  Adapter --> RequestHook[Request Hook]
  Adapter --> Route[Route Handler]
  Route --> ResponseHelpers[reply / status / render / redirect / end]
  Adapter --> ResponseHook[Response Hook]
  Adapter --> ErrorHandler[Error Handler]
  Adapter --> NotFoundHandler[Not Found Handler]

Usage

ts
import express from 'express';
import { ExpressAdapter } from '@nestjs/platform-express';

const server = express();
const adapter = new ExpressAdapter(server);

adapter.setOnRequestHook((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
});

adapter.setOnResponseHook((req, res, next) => {
  res.on('finish', () => {
    console.log(`Response completed with ${res.statusCode}`);
  });
  next();
});

server.get('/health', (_req, res) => {
  adapter.reply(res, { status: 'ok' }, 200);
});

server.get('/dashboard', (_req, res) => {
  adapter.render(res, 'dashboard', { title: 'Dashboard' });
});

adapter.setNotFoundHandler((req, res) => {
  adapter.status(res, 404);
  adapter.reply(res, { message: `Route not found: ${req.url}` }, 404);
});

adapter.setErrorHandler((error, _req, res, _next) => {
  console.error(error);

  if (!adapter.isHeadersSent(res)) {
    adapter.reply(res, { message: 'Internal server error' }, 500);
  }
});

server.listen(3000);

AI Coding Instructions

• Use adapter response helpers such as reply(), status(), redirect(), and end() instead of directly coupling shared platform code to Express response APIs.
• Register request and response hooks early, before routes or framework initialization, so they apply consistently to all requests.
• Check isHeadersSent(response) before writing an error response to prevent duplicate headers or response-write errors.
• Ensure custom error and not-found handlers terminate the response and preserve Express middleware signatures.
• Keep Express-specific middleware and view-engine configuration at the platform boundary; application logic should remain adapter-agnostic.

How it works

ExpressAdapter is a public class that extends Nest’s AbstractHttpAdapter with an Express application instance and an HTTP or HTTPS Node server type. Its constructor accepts an optional application instance; otherwise it creates one with express(). [packages/platform-express/adapters/express-adapter.ts:48-53] [packages/platform-express/adapters/express-adapter.ts:67-82]

Relationships

• IMPORTS → HttpStatus
• IMPORTS → InternalServerErrorException
• IMPORTS → Logger
• IMPORTS → RequestMethod
• IMPORTS → StreamableFile
• IMPORTS → VERSION_NEUTRAL
• IMPORTS → VersioningOptions
• IMPORTS → VersioningType
• IMPORTS → VersionValue
• IMPORTS → CorsOptions
• IMPORTS → CorsOptionsDelegate
• IMPORTS → NestApplicationOptions
• IMPORTS → isFunction
• IMPORTS → isNil
• IMPORTS → isObject
• IMPORTS → isString
• IMPORTS → isUndefined
• IMPORTS → AbstractHttpAdapter
• IMPORTS → RouterMethodFactory
• IMPORTS → LegacyRouteConverter