Adaptador Express

El adaptador Express de Veloce-TS te permite montar una aplicación Veloce-TS dentro de una app Express.js existente — o usar Express como capa de transporte HTTP. Es útil cuando migras de Express a Veloce-TS de forma incremental, o cuando necesitas middleware exclusivo de Express (Passport.js, multer, sesiones, etc.).

:::note Reescritura en v0.4.0 El adaptador Express fue completamente reescrito en v0.4.0 para compatibilidad total con ESM, manejo correcto del body y delegación apropiada de errores. Si usabas una versión anterior, revisa las notas de migración. :::

Tabla de Contenidos

Instalación
Uso Básico
Agregar Middleware Express Antes del Puente
Montar en una Sub-Ruta
Manejo de Errores
Migración desde Versiones Anteriores
Cuándo Usar el Adaptador Express

Instalación

Express es una peer dependency — instálala junto a Veloce-TS:

# Usando Bun
bun add veloce-ts express
bun add -d @types/express

# Usando npm
npm install veloce-ts express
npm install --save-dev @types/express

Uso Básico

import express from 'express';
import { VeloceTS, Controller, Get, Post, Body } from 'veloce-ts';
import { ExpressAdapter } from 'veloce-ts/adapters/express';
import { z } from 'zod';

// 1. Define tu app Veloce-TS normalmente
const UsuarioSchema = z.object({
  nombre: z.string().min(2),
  email: z.string().email(),
});

@Controller('/usuarios')
class UsuarioController {
  @Get('/')
  async listar() {
    return [{ id: 1, nombre: 'Juan' }];
  }

  @Post('/')
  async crear(@Body(UsuarioSchema) usuario: z.infer<typeof UsuarioSchema>) {
    return { id: 2, ...usuario };
  }
}

const veloce = new VeloceTS({ title: 'Mi API', docs: true });
veloce.include(UsuarioController);
await veloce.compile();

// 2. Crea una app Express y monta Veloce-TS
const app = express();
app.use(express.json());

// Monta el adaptador — maneja todas las peticiones bajo /api
const adapter = new ExpressAdapter(veloce);
app.use('/api', adapter.getRouter());

// Puedes tener rutas Express normales junto a las de Veloce-TS
app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.listen(3000, () => {
  console.log('Servidor en http://localhost:3000');
  console.log('Rutas Veloce-TS en http://localhost:3000/api');
  console.log('Swagger UI en http://localhost:3000/api/docs');
});

Agregar Middleware Express Antes del Puente

El adaptador v0.4.0 acepta una app Express pre-creada como segundo argumento. Esto permite agregar middleware (auth, rate limiting, multipart, etc.) que se ejecuta antes de que las peticiones lleguen a Veloce-TS:

import express from 'express';
import passport from 'passport';
import multer from 'multer';
import { ExpressAdapter } from 'veloce-ts/adapters/express';

const expressApp = express();

// Agrega el middleware Express que necesites
expressApp.use(express.json());
expressApp.use(express.urlencoded({ extended: true }));
expressApp.use(passport.initialize());

const upload = multer({ dest: 'uploads/' });

// Crea el adaptador pasando la app Express pre-configurada
const adapter = new ExpressAdapter(veloce, expressApp);

expressApp.use('/api', adapter.getRouter());
expressApp.listen(3000);

Montar en una Sub-Ruta

Monta Veloce-TS en cualquier sub-ruta de tu app Express:

const mainApp = express();
mainApp.use(express.json());

// API v1 con Veloce-TS
const v1Adapter = new ExpressAdapter(veloceV1App);
mainApp.use('/api/v1', v1Adapter.getRouter());

// API v2 con otra app Veloce-TS
const v2Adapter = new ExpressAdapter(veloceV2App);
mainApp.use('/api/v2', v2Adapter.getRouter());

// Rutas legadas en Express
mainApp.use('/legacy', legacyRouter);

mainApp.listen(3000);

Manejo de Errores

El adaptador v0.4.0 delega correctamente los errores inesperados al pipeline de errores de Express via next(err):

import express, { Request, Response, NextFunction } from 'express';
import { ExpressAdapter } from 'veloce-ts/adapters/express';

const app = express();
app.use(express.json());

const adapter = new ExpressAdapter(veloce);
app.use('/api', adapter.getRouter());

// Este handler de errores se llama para errores no manejados
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  console.error('Error no manejado:', err);
  res.status(500).json({
    error: 'Error interno del servidor',
    message: process.env.NODE_ENV === 'development' ? err.message : undefined,
  });
});

app.listen(3000);

Manejo del Body

El adaptador v0.4.0 maneja correctamente tanto bodies raw (Buffer) como pre-parseados:

JSON/urlencoded: Si el middleware Express ya parseó el body, el adaptador usa el valor parseado
Buffer raw: Si el body es raw (p.ej. webhooks, subida de archivos), se pasa correctamente
Header transfer-encoding: El adaptador omite este header al reenviar respuestas (era fuente de bugs en versiones anteriores)

Migración desde Versiones Anteriores

Ruta de importación

// Antes (v0.3.x)
import { ExpressAdapter } from 'veloce-ts';

// Ahora (v0.4.0)
import { ExpressAdapter } from 'veloce-ts/adapters/express';

Compatibilidad ESM

El adaptador ya no necesita workarounds como declare const require: any. Usa Function('return require')() internamente para cargar Express de forma lazy, lo que funciona perfectamente en proyectos ESM.

Cuándo Usar el Adaptador Express

Escenario	Recomendación
Proyecto nuevo	Usar Veloce-TS standalone (adaptador Hono) para mejor rendimiento
Migrar una app Express a Veloce-TS	Usar el adaptador para migrar ruta por ruta
Necesitas Passport.js, multer u otro middleware solo de Express	Usar el adaptador
Plataforma que solo soporta Express	Usar el adaptador
Necesitas máximo rendimiento	Usar Veloce-TS standalone

Próximos Pasos

Aprende sobre Plugins para extender Veloce-TS
Explora Inyección de Dependencias
Lee la Guía de Inicio