@truxie/express

Express / Node HTTP adapter for truxie — run your truxie controllers on a standalone Node server (Express, Connect, or bare node:http) with no Next.js dependency.

The dispatcher routes requests through the full truxie pipeline (guards → pipes → interceptors → handler → filters), identical to @truxie/next and @truxie/nitro. The native request exposed to your code is a standard Web Request, so param decorators and helpers written for the Next.js adapter (ctx.getNativeRequest() as Request, @RawBody(), @Ip(), @Headers()) work unchanged.

Install

npm install @truxie/express truxie

Usage

Bare node:http (no Express needed)

import 'reflect-metadata';
import {createServer} from 'node:http';
import {TruxieFactory} from 'truxie';
import {createExpressDispatcher} from '@truxie/express';
import {AppModule} from './app.module';

const app = await TruxieFactory.create(AppModule);
app.setGlobalPrefix('api');

createServer(createExpressDispatcher({app})).listen(3000, '127.0.0.1');

Express

import express from 'express';
import {createExpressDispatcher} from '@truxie/express';

const server = express();
// fallthrough: true → unmatched requests continue to downstream middleware
server.use(createExpressDispatcher({app, fallthrough: true}));
server.use(express.static('public'));
server.listen(3000);

Important notes

• Do not put a body parser in front of the dispatcher. It reads the raw request stream itself so @RawBody() (webhook signature verification) receives the exact original bytes. If an upstream express.json() already consumed the stream, plain @Body() still works (the parsed body is re-serialized) but raw-body byte fidelity is lost.
• app.setGlobalPrefix('api') works as usual — routes are matched against the full pathname (req.originalUrl when mounted under Express, preserving the mount path).
• Client disconnects abort the request's AbortSignal (ctx.getSignal()), same semantics as the Nitro adapter.
• Controllers may return a Web Response directly; status, headers (including multiple Set-Cookie), and body are copied to the Node response.

Options

| Option | Type | Default | Description | |---|---|---|---| | app | TruxieApplication | — | The initialized truxie application | | fallthrough | boolean | false | On no route match: false → 404 JSON response, true → call Express next() |

License

MIT