createServerApp

createServerApp es la aplicación de servidor de Meeko: recibe el manifiesto que fija el build (rutas, endpoints, canales, middleware y assets), un cargador que devuelve cada módulo por su clave y el runtime de server/runtime.ts, y devuelve un objeto con fetch(request) que atiende todo: middleware de servidor, archivos públicos, páginas prerenderizadas, SSR, payloads de navegación, API, RPC y el hub de Socket. Llama una vez a la fábrica del runtime y, si no declara sessions, crea las de por defecto.

Es lo que usan las entradas que genera meeko build para Node, Bun, Deno y Cloudflare. Se usa directamente para alojar la aplicación en un host propio o para probarla sin red, llamando a app.fetch.

Uso#

// server/host.ts, empaquetado con Vite y el plugin meeko()
import { createServerApp } from "@meekojs/meeko/server";
import { serveNode } from "@meekojs/meeko/node";
import { appName, load, loadRedis, manifest, plugins, runtime } from "virtual:meeko-server-app";

const app = await createServerApp({ manifest, load, runtime, plugins, appName, loadRedis, production: true });
const server = await serveNode(app, { port: 3000, handleSignals: true });
console.log(server.url);

virtual:meeko-server-app es el módulo que el plugin de Vite genera con el manifiesto y los cargadores del proyecto; es lo mismo que importa .meeko/generated/entry-server.ts.

Tipo#

function createServerApp<Env = Readonly<Record<string, string | undefined>>>(
  options: ServerAppOptions<Env>,
): Promise<ServerApp>

interface ServerAppOptions<Env = Readonly<Record<string, string | undefined>>> {
	readonly manifest: AppManifest
	readonly load: AppModuleLoader
	readonly runtime?: ServerRuntimeDefinition<Env, any> | undefined
	readonly production: boolean
	readonly appName?: string | undefined
	readonly loadRedis?: (() => Promise<unknown>) | undefined
	readonly platform?: ServerPlatform<Env>
	readonly assets?: AssetReader
	readonly prerender?: PrerenderSource
	readonly document?: DocumentOptions
	readonly publicOrigin?: string
	readonly prerendering?: boolean
	readonly root?: string | undefined
	readonly defaultSocketPubSub?: SocketPubSub
	readonly plugins?: readonly PluginRegistration[]
}

interface ServerApp {
	fetch(request: Request, platform?: ServerPlatform): Promise<Response>
	readonly socket?: ServerAppSocket
	readonly manifest: AppManifest
	readonly publicOrigin?: string
	reportError(error: unknown, requestId: string, info?: ServerErrorInfo): void
	close(): Promise<void>
}

interface AppManifest {
  readonly version: 1;
  readonly routes: readonly RouteRecord[];
  readonly errorPage?: ErrorPageRecord | undefined;
  readonly server: ServerManifest;
  readonly routeMiddleware: readonly string[];
  readonly serverMiddleware: readonly string[];
  readonly serverHandlers?: readonly { readonly route: string; readonly file: string }[];
  readonly client: ClientAssets;
  readonly assets?: AssetManifest;
  readonly document?: DocumentConfig | undefined;
  readonly contentSecurityPolicy?: ContentSecurityPolicy | undefined;
  readonly headers?: ServerHeaders | undefined;
  readonly publicFileHeaders?:
    Readonly<Record<string, Readonly<Record<string, string>>>> | undefined;
  readonly buildId?: string | undefined;
}

Opciones#

Valor devuelto#

Una promesa de ServerApp:

Rechaza con TypeError si el manifiesto es de otra versión (Unsupported Meeko application manifest; rebuild the application), falta el cargador (createServerApp requires a module loader), publicOrigin no es HTTP(S) o el runtime devuelve algo que no es un objeto o unas sessions que no son un SessionManager; y con Error en producción sin almacén persistente.

Ejemplos#

Una aplicación mínima, sin red#

import { createServerApp, defineApiRoute } from "@meekojs/meeko/server";
import type { AppManifest, Schema } from "@meekojs/meeko/server";

const health: Schema<{ ok: boolean }> = {
  "~standard": { version: 1, validate: (value) => ({ value: value as { ok: boolean } }) },
};
const modules: Record<string, unknown> = {
  "/server/api/health.get.ts": { default: defineApiRoute({ response: health, handler: () => ({ ok: true }) }) },
};
const manifest: AppManifest = {
  version: 1,
  routes: [],
  routeMiddleware: [],
  serverMiddleware: [],
  server: {
    api: [{ kind: "api", file: "/server/api/health.get.ts", pathname: "/api/health", method: "GET", clientKey: "health" }],
    rpc: [],
    socket: [],
  },
  client: { entry: "/assets/entry.js", css: [], preload: [] },
};

const app = await createServerApp({ manifest, load: async (key) => modules[key], production: false });
const response = await app.fetch(new Request("http://localhost/api/health"));
console.log(response.status, await response.json()); // 200 { ok: true }
await app.close();

Un POST /api/health responde 405 con Allow: GET, y /otra responde 404 Not Found.

Probar el build de Node sin abrir un puerto#

// tests/smoke.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { createNodeApp } from "../.meeko/output/node/index.mjs";

test("la portada responde", async () => {
  const app = await createNodeApp();
  const response = await app.fetch(new Request("http://localhost/", { headers: { accept: "text/html" } }));
  assert.equal(response.status, 200);
  await app.close();
});

createNodeApp del build llama a createServerApp con el manifiesto, los assets y las páginas prerenderizadas del build. Como es producción, necesita MEEKO_REDIS_URL o sessions en server/runtime.ts.

Un host con su propio nonce#

const app = await createServerApp({
  manifest, load, runtime, production: true,
  document: {
    nonce: (request) => request.headers.get("x-csp-nonce") ?? undefined,
    bodyEnd: ({ nonce }) => `<script nonce="${nonce ?? ""}" src="/analytics.js" defer></script>`,
  },
});

Con server.contentSecurityPolicy (desde 1.7), Meeko genera un nonce por respuesta él mismo; DocumentOptions.nonce sólo hace falta cuando el host fija la CSP.

Errores comunes#

Producción sin sesiones persistentes#

const app = await createServerApp({ manifest, load, production: true });

Rechaza con Production requires a persistent session store: set MEEKO_REDIS_URL (with the redis package installed), or return { sessions } with a persistent SessionStore from server/runtime.ts.

const app = await createServerApp({ manifest, load, runtime, production: true, platform: { name: "node", env: process.env } });

Con MEEKO_REDIS_URL en platform.env (y loadRedis), o con sessions en el runtime.

Un manifiesto de otra versión de Meeko#

import manifest from "./old-build/manifest.json";
await createServerApp({ manifest, load, production: false });

TypeError: Unsupported Meeko application manifest; rebuild the application. El manifiesto y el runtime deben venir del mismo @meekojs/meeko.

// vuelve a ejecutar meeko build y usa el manifiesto nuevo
const app = await createServerApp({ manifest, load, production: false });

Unas sessions que no son un SessionManager#

const runtime = () => ({ sessions: new MemorySessionStore() });

TypeError: server/runtime.ts must return { sessions: SessionManager } or omit sessions: el almacén va dentro del gestor.

const runtime = defineServerRuntime(() => ({ sessions: new SessionManager({ store: new MemorySessionStore() }) }));

Notas#

• Portable. Sólo usa Web APIs (Request, Response, Web Crypto) y node:async_hooks: la misma aplicación funciona en Node, Bun, Deno y Workers con el adaptador de cada uno.
• Cierre. close() espera las tareas de waitUntil y cierra el runtime; no cierra el servidor HTTP ni las conexiones Socket, que son del adaptador. serveNode({ handleSignals: true }) lo hace todo en orden.
• Cookies y cachés. Toda respuesta con Set-Cookie y un Cache-Control public sale como private, no-store y sin ETag, para que ninguna caché compartida guarde la cookie.
• CSP. Desde 1.7, con manifest.contentSecurityPolicy, cada respuesta en producción lleva su política: hashes en las páginas prerenderizadas, un nonce en SSR y default-src 'none' en el JSON. En desarrollo no se aplica.
• Errores. Los fallos de las peticiones van al onError del runtime (o a la consola, con el requestId); en producción, el navegador nunca recibe la traza.

Relacionado#

• serveNodeSirve una aplicación de Meeko con el servidor HTTP de Node, sus canales Socket con ws, el cierre ordenado ante señales y la política de fallos del proceso.
• createBunServerLos handlers fetch y websocket para servir una aplicación de Meeko con Bun.serve, con Socket sobre el WebSocket nativo de Bun y sus límites de payload, contrapresión e inactividad.
• serveDenoSirve una aplicación de Meeko con Deno.serve, con Socket sobre Deno.upgradeWebSocket, cierre ordenado ante señales y la política de fallos del proceso.
• createWorkerSirve una aplicación de Meeko desde un Worker de módulo de Cloudflare, creada una vez por aislado con los bindings, con los upgrades de Socket reenviados al Durable Object de su sala.
• defineServerRuntimeDeclara en server/runtime.ts las sesiones, los servicios, la política de Socket y el cierre de la aplicación, creados una vez por proceso.
• createFrameworkHandlerCrea un handler Fetch que renderiza las páginas de la aplicación (middleware de ruta, validación, loader, SSR, payload de navegación y páginas de error) para un host propio.
• Runtime de servidorMeeko como framework full-stack
• Build, despliegue y verificaciónMeeko como framework full-stack