serveNode

serveNode(app, options) starts a node:http server for a createServerApp application: it converts each request with toNodeListener, connects Socket channels to the same server with attachNodeWebSocketServer (if the application has them) and, with handleSignals, shuts down gracefully on SIGINT and SIGTERM and applies processErrors. This is what the Node output of meeko build runs (.meeko/output/node/index.mjs, started by meeko start).

Write it manually only for a custom host; with the node adapter, meeko build already generates the entry point.

Usage#

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(`Listening on ${server.url}`);

Type#

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>
}

Parameters#

serveNode(app, options?):

Return value#

A promise with a NodeServer:

If the server starts but Socket attachment fails, it releases the port and closes the application before rejecting.

Examples#

Production with 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 and MEEKO_PORT (or PORT) override server.host and server.port. The .meeko/output/node/ folder does not read app/ or server/: it only needs node_modules, including @meekojs/meeko.

A container#

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"]

The generated entry point calls serveNode with handleSignals: true: the orchestrator's SIGTERM closes Socket, HTTP, waitUntil tasks and the runtime, in that order.

An available port in tests#

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();
}

Common mistakes#

Listening on 127.0.0.1 inside a container#

docker run -p 3000:4173 tienda   # without MEEKO_HOST

There is no error: the server listens on the container's loopback, and the published port cannot reach it. The client sees a refused or closed connection.

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

An invalid MEEKO_TRUST_PROXY#

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

Startup stops with TypeError: MEEKO_TRUST_PROXY must be true, false or the number of trusted proxies (1-99), or cloudflare, not "yes": serveNode checks the variable before listening, not on every request.

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

An out-of-range port#

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

RangeError: Invalid port: 70000. In meeko.config.ts, an out-of-range server.port stops meeko build with server.port debe ser un entero entre 0 y 65535.

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

Behind a proxy without publicOrigin#

# Caddy terminates TLS at https://tienda.example.com and forwards to http://127.0.0.1:4173
node .meeko/output/node/index.mjs

API and RPC mutations (since 1.8, also without a session) respond with 403 INVALID_ORIGIN, and browser Socket upgrades with 403: the application compares Origin with its own address, not the public one.

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

Notes#

• Node 24. The adapter uses node:http and Web Streams; Set-Cookie headers are sent separately.
• Socket. It uses the ws package (loaded only if the application has channels), with frames up to socket.maxMessageBytes (64 KiB by default), no compression and a 30 s heartbeat. Binary messages are closed with 1003.
• Assets. The application serves them from its manifest (createNodeAssetReader): it never reads a disk path not listed there.
• Client IP. context.clientAddress and clientAddress(request) are the remote socket; behind a proxy, MEEKO_TRUST_PROXY=1 takes the entry the proxy added to X-Forwarded-For, and behind Cloudflare Tunnel (since 1.8), MEEKO_TRUST_PROXY=cloudflare takes CF-Connecting-IP if the connection comes from networks in MEEKO_TRUSTED_PROXIES.
• CSP and headers (since 1.7). server.contentSecurityPolicy and server.headers from meeko.config.ts apply to every production response, with a nonce per SSR response and hashes for prerendered ones.
• Request-target. A path starting with // is always on the same origin, never another host.

Related#

• toNodeListenerAdapts a Fetch handler to Node's http.createServer callback, with streaming, multiple Set-Cookie headers, cancellation on client disconnect and the connection's IP.
• attachNodeWebSocketServerConnects Meeko Socket channels to a Node HTTP server through the ws package, with a frame limit, heartbeat and shutdown of all peers.
• createNodeAssetReaderServes only build files listed in the asset manifest from disk on Node, using streaming and Meeko's ETag, HEAD, 304 and cache policy.
• createServerAppCreates the portable server application (pages, API, RPC, Socket, assets, sessions and middleware) from the build manifest and a module loader.
• handleProcessErrorsApplies server/runtime.ts processErrors policy to a custom host for unhandled rejections and uncaught exceptions outside a request.
• serverThe meeko build adapter (node, bun, deno, cloudflare or static) and its options, plus, since 1.7, response CSP and headers for server adapters.
• meeko startStarts the Node production server using meeko build output, without Vite or application sources.
• Build, deployment and verificationMeeko as a full-stack framework
• Client IP behind a proxyMeeko as a full-stack framework