createFrameworkHandler

createFrameworkHandler is the page part of createServerApp, separated for custom hosts: it takes the route manifest and module loaders and returns a (request) => Promise<Response> handler doing everything a page needs: route middleware (isomorphic and server), params and search validation, the loader or <script server>, SSR rendering (including "stream" and "client"), the navigation payload (Accept: application/meeko+json), layouts and error pages.

It does not handle API, RPC, Socket or files, run server/middleware middleware or create sessions: those belong to the host or createServerApp.

Usage#

import { createFrameworkHandler } from "@meekojs/meeko/server";
import type { PageModule } from "@meekojs/meeko/server";

const hello: PageModule = {
  renderWithState: (props) => ({ html: `<h1>Hello, ${String((props.params as Record<string, string>).name)}</h1>`, state: {} }),
};

const handlePage = createFrameworkHandler({
  routes: [{ id: "/hello/[name]", file: "app/pages/hello/[name].meeko", layouts: [] }],
  loadPage: async () => hello,
  clientEntry: "/assets/entry-client.js",
});

const response = await handlePage(new Request("http://localhost/hello/ada", { headers: { accept: "text/html" } }));
console.log(response.status, response.headers.get("content-type")); // 200 text/html; charset=utf-8

Type#

function createFrameworkHandler(
  options: FrameworkHandlerOptions,
): (request: Request) => Promise<Response>

function createFrameworkHandler<Route extends TypedPageRoute>(
  options: FrameworkHandlerOptions<Route>,
): (request: Request) => Promise<Response>

interface FrameworkHandlerOptions<Route = PageRoute> {
	readonly routes: readonly RouteRecord[]
	readonly errorPage?: ErrorPageRecord | undefined
	readonly loadPage: (file: string) => Promise<PageModule>
	readonly loadRoute?: (file: string) => Promise<Route>
	readonly loadMiddleware?: () => Promise<readonly RouteMiddleware[]>
	readonly loadNamedMiddleware?: (file: string) => Promise<RouteMiddleware>
	readonly loadServerMiddleware?: (file: string) => Promise<ServerRouteMiddleware>
	readonly createContext?: (request: Request) => RequestContext | Promise<RequestContext>
	readonly serverFetch?: ServerFetch
	readonly onError?: (error: unknown, requestId: string) => void
	readonly clientEntry?: string
	readonly document?: DocumentOptions
	readonly plugins?: readonly PluginRegistration[]
}

interface DocumentOptions {
	readonly head?: DocumentMarkup
	readonly bodyEnd?: DocumentMarkup
	readonly nonce?: (request: Request) => string | undefined
	readonly config?: DocumentConfig
}

Options#

Return value#

(request: Request) => Promise<Response>. Depending on the request and route:

Examples#

Pages with layouts, a sidecar and the navigation payload#

import { createFrameworkHandler } from "@meekojs/meeko/server";
import type { PageModule, PageRoute } from "@meekojs/meeko/server";

const page = (html: string): PageModule => ({ renderWithState: () => ({ html, state: {} }) });
const pages: Record<string, PageModule> = { "app/pages/index.meeko": page("<h1>Home</h1>") };
const sidecars: Record<string, PageRoute> = { "app/pages/index.route.ts": { head: () => ({ title: "Home" }) } };

const handlePage = createFrameworkHandler({
  routes: [{ id: "/", file: "app/pages/index.meeko", layouts: [], sidecar: "app/pages/index.route.ts" }],
  loadPage: async (file) => pages[file]!,
  loadRoute: async (file) => sidecars[file]!,
  clientEntry: "/assets/entry-client.js",
});

const data = await handlePage(new Request("http://localhost/", { headers: { accept: "application/meeko+json" } }));
console.log(data.headers.get("content-type")); // application/meeko+json; charset=utf-8

With a session and services#

import { createFrameworkHandler, createLocalServerFetch, createRequestContext } from "@meekojs/meeko/server";

const handlePage = createFrameworkHandler({
  routes, errorPage, loadPage, loadRoute,
  createContext: async (request) => createRequestContext(request, { db }, await sessions.load(request)),
  serverFetch: createLocalServerFetch({ manifest: serverManifest, sessions, services: { db }, load }),
  clientEntry: "/assets/entry-client.js",
});

serverFetch keeps await api.users.list() inside a page off the network during SSR.

Common mistakes#

A route with named middleware but no loader#

createFrameworkHandler({ routes, loadPage });   // a route declares middleware: ["auth"]

The request to that route fails instead of skipping middleware, because middleware protecting a route is never silently ignored: it responds with 500 Internal Server Error and onError receives Route / has named middleware (/app/middleware/auth.ts) but no loadNamedMiddleware to load it.

createFrameworkHandler({ routes, loadPage, loadNamedMiddleware: async (file) => (await import(file)).default });

Expect it to handle the API#

const response = await handlePage(new Request("http://localhost/api/users"));

/api/users is not a page route: the response is 404 Not Found. API and RPC are handled by createServerDispatcher (or createServerApp, which combines everything).

const url = new URL(request.url);
const response = url.pathname.startsWith("/api/") || url.pathname.startsWith("/_meeko/rpc/") ? await dispatch(request) : await handlePage(request);

Forget clientEntry#

createFrameworkHandler({ routes, loadPage });

HTML renders, but the document links no script: the page does not hydrate and links cause full navigations.

createFrameworkHandler({ routes, loadPage, clientEntry: "/assets/entry-client.js" });

Notes#

• Server. Runs in any runtime with Fetch; it does not read disk or import anything not supplied by the loaders.
• Hydration. The browser must mount with mountClientApp and the same routes; the payload checks that route and parameters match.
• Server middleware. Does not run server/middleware (defineServerMiddleware): wrap the handler with composeServerMiddleware if needed.
• Security. Internal errors are reported to onError with a requestId and the browser only receives the status and public message. Escape everything you put in document.head and bodyEnd: it is trusted HTML.
• Prerendering. prerenderRoutes accepts this handler as handler to write static HTML.

Related#

• createServerAppCreates the portable server application (pages, API, RPC, Socket, assets, sessions and middleware) from the build manifest and a module loader.
• createServerDispatcherCreates an HTTP handler that serves /api/... and /_meeko/rpc/... on your own host, with the same sessions, guards, validation and errors as the application.
• createRequestContextCreates a request's RequestContext (session, services, platform, requestId and signal) for a custom host or to test an endpoint without a server.
• mountClientAppHydrates server-rendered HTML in the browser and manages client navigation, with history, links, route middleware, data payloads and cleanup.
• prerenderRoutesPrerenders render "prerender" routes with a page handler and writes their HTML, navigation payloads and manifest.json index.
• Routing, layouts and SSRMeeko as a full-stack framework
• Application pluginsMeeko as a full-stack framework