serveNode

serveNode(app, options) pone en marcha un servidor node:http para una aplicación de createServerApp: convierte cada petición con toNodeListener, conecta los canales Socket al mismo servidor con attachNodeWebSocketServer (si la aplicación los tiene) y, con handleSignals, cierra de forma ordenada ante SIGINT y SIGTERM y aplica processErrors. Es lo que ejecuta la salida de meeko build para Node (.meeko/output/node/index.mjs, la que arranca meeko start).

Escríbalo a mano sólo para un host propio; con el adaptador node, meeko build ya genera el entry.

Uso#

import { createServerApp } from "@meekojs/meeko/server";
import { serveNode } from "@meekojs/meeko/node";

const app = await createServerApp({ manifest, load, runtime, production: true });
const server = await serveNode(app, { host: "0.0.0.0", port: 3000, publicOrigin: "https://example.com", handleSignals: true });
console.log(`Escuchando en ${server.url}`);

Tipo#

function serveNode(app: ServerApp, options?: ServeNodeOptions): Promise<NodeServer>

interface ServeNodeOptions {
	readonly host?: string
	readonly port?: number
	readonly publicOrigin?: string
	readonly platform?: ServerPlatform
	readonly onError?: (error: unknown, requestId: string) => void
	readonly handleSignals?: boolean
	readonly shutdownTimeout?: number
}

interface NodeServer {
	readonly server: Server
	readonly url: string
	close(): Promise<void>
}

Parámetros#

serveNode(app, options?):

Valor devuelto#

Una promesa con un NodeServer:

Si el servidor arranca pero falla la conexión de Socket, libera el puerto y cierra la aplicación antes de rechazar.

Ejemplos#

Producción con meeko start#

// meeko.config.ts
import { defineMeekoConfig } from "@meekojs/meeko/framework";

export default defineMeekoConfig({ server: { adapter: "node", host: "0.0.0.0", port: 3000 } });

npm run build
MEEKO_PUBLIC_ORIGIN=https://tienda.example.com MEEKO_REDIS_URL=rediss://… MEEKO_TRUST_PROXY=1 npm start

MEEKO_HOST y MEEKO_PORT (o PORT) sustituyen a server.host y server.port. La carpeta .meeko/output/node/ no lee app/ ni server/: sólo necesita node_modules, @meekojs/meeko incluido.

Un contenedor#

FROM node:24-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY .meeko/output/node ./.meeko/output/node
ENV MEEKO_HOST=0.0.0.0 MEEKO_PORT=3000
EXPOSE 3000
CMD ["node", ".meeko/output/node/index.mjs"]

El entry generado llama a serveNode con handleSignals: true: el SIGTERM del orquestador cierra Socket, HTTP, las tareas de waitUntil y el runtime, por ese orden.

Un puerto libre en las pruebas#

const node = await serveNode(app, { port: 0 });
try {
  const response = await fetch(`${node.url}/api/health`);
  assert.equal(response.status, 200);
} finally {
  await node.close();
}

Errores comunes#

Escuchar en 127.0.0.1 dentro de un contenedor#

docker run -p 3000:4173 tienda   # sin MEEKO_HOST

No hay error: el servidor escucha en el loopback del contenedor y el puerto publicado no llega a él. El cliente ve la conexión rechazada o cortada.

docker run -p 3000:3000 -e MEEKO_HOST=0.0.0.0 -e MEEKO_PORT=3000 tienda

Un MEEKO_TRUST_PROXY no válido#

MEEKO_TRUST_PROXY=yes node .meeko/output/node/index.mjs

El arranque se detiene con TypeError: MEEKO_TRUST_PROXY must be true, false or the number of trusted proxies (1-99), or cloudflare, not "yes": serveNode comprueba la variable antes de escuchar, no en cada petición.

MEEKO_TRUST_PROXY=1 node .meeko/output/node/index.mjs

Un puerto fuera de rango#

await serveNode(app, { port: 70000 });

RangeError: Invalid port: 70000. En meeko.config.ts, server.port fuera de rango detiene meeko build con server.port debe ser un entero entre 0 y 65535.

await serveNode(app, { port: Number(process.env.MEEKO_PORT ?? 4173) });

Tras un proxy sin publicOrigin#

# Caddy termina TLS en https://tienda.example.com y reenvía a http://127.0.0.1:4173
node .meeko/output/node/index.mjs

Las mutaciones de API y RPC (desde 1.8, también sin sesión) responden 403 INVALID_ORIGIN, y los upgrades de Socket del navegador, 403: la aplicación compara Origin con su propia dirección, no con la pública.

MEEKO_PUBLIC_ORIGIN=https://tienda.example.com node .meeko/output/node/index.mjs

Notas#

• Node 24. El adaptador usa node:http y Web Streams; las cabeceras Set-Cookie se envían por separado.
• Socket. Usa el paquete ws (se carga sólo si la aplicación tiene canales), con frames de hasta socket.maxMessageBytes (64 KiB por defecto), sin compresión y con heartbeat de 30 s. Los mensajes binarios se cierran con 1003.
• Assets. Los sirve la aplicación desde su manifiesto (createNodeAssetReader): nunca lee del disco una ruta que no esté en él.
• IP del cliente. context.clientAddress y clientAddress(request) son el socket remoto; tras un proxy, MEEKO_TRUST_PROXY=1 toma la entrada que añadió el proxy en X-Forwarded-For, y tras Cloudflare Tunnel (desde 1.8), MEEKO_TRUST_PROXY=cloudflare toma CF-Connecting-IP si la conexión viene de las redes de MEEKO_TRUSTED_PROXIES.
• CSP y cabeceras (desde 1.7). server.contentSecurityPolicy y server.headers de meeko.config.ts se aplican a cada respuesta en producción, con un nonce por respuesta SSR y hashes en las prerenderizadas.
• Request-target. Una ruta que empieza por // es siempre del origen propio, nunca otro host.

Relacionado#

• toNodeListenerAdapta un handler Fetch al callback de http.createServer de Node, con streaming, varias Set-Cookie, cancelación al desconectarse el cliente y la IP de la conexión.
• attachNodeWebSocketServerConecta los canales Socket de Meeko a un servidor HTTP de Node con el paquete ws, con límite de frame, heartbeat y cierre de todos los peers.
• createNodeAssetReaderSirve desde el disco, en Node, sólo los archivos del build listados en el manifiesto de assets, en streaming y con ETag, HEAD, 304 y la política de caché de Meeko.
• createServerAppCrea la aplicación de servidor portable (páginas, API, RPC, Socket, assets, sesiones y middleware) a partir del manifiesto del build y un cargador de módulos.
• handleProcessErrorsAplica a un host propio la política processErrors de server/runtime.ts para los rechazos sin manejar y las excepciones no capturadas fuera de una petición.
• serverEl adaptador de meeko build (node, bun, deno, cloudflare o static) con sus opciones y, desde 1.7, la CSP y las cabeceras de las respuestas en los adaptadores con servidor.
• meeko startArranca el servidor de producción de Node con la salida de meeko build, sin Vite ni las fuentes de la aplicación.
• Build, despliegue y verificaciónMeeko como framework full-stack
• IP del cliente tras un proxyMeeko como framework full-stack