Reference

FaceModule API reference

The FaceModule is the atomic unit of FaceTheory’s routing model. A consumer declares an array of FaceModules and passes them to createFaceApp; the runtime picks the correct rendering pipeline per Face based on its declared mode.

FaceModule

interface FaceModule {
  route: string;
  mode: FaceMode;
  generateStaticParams?: () => Promise<Array<Record<string, string>>>;
  revalidateSeconds?: number;
  load?: (ctx: FaceContext) => Promise<unknown>;
  render: (
    ctx: FaceContext,
    data: unknown,
  ) => Promise<FaceRenderResult> | FaceRenderResult;
}

route

A URL pattern. Path parameters use {name} syntax (e.g. /blog/{slug}).

mode

type FaceMode = 'ssr' | 'ssg' | 'isr';

Only three values are valid. 'spa' is not a FaceMode — SPA navigation is a client-side runtime layered on top of a server-rendered shell, started via startFaceNavigation() from a bootstrap module. See SPA navigation.

generateStaticParams

Required for parameterized SSG routes; optional otherwise. Returns the matrix of params to render at build time.

revalidateSeconds

Used by mode: 'isr' to determine cache freshness. The cached entry is served until it ages past this value; the next request after expiry triggers a regeneration.

load

Optional pre-render data loader. The return value is passed as the data argument to render.

render

The render function. Receives the FaceContext and any load-returned data; returns a FaceRenderResult (synchronously or as a Promise).

FaceContext

interface FaceContext {
  request: Readonly<Required<FaceRequest>>;
  params: Readonly<Record<string, string>>;
  proxy: string | null;
}

FaceRequest

interface FaceRequest {
  method: string;
  path: string;
  query?: Query;
  headers?: Headers;
  cookies?: CookieMap;
  body?: Uint8Array;
  isBase64?: boolean;
  cspNonce?: string | null;
}

FaceResponse

interface FaceResponse {
  status: number;
  headers: Headers;
  cookies: string[];
  body: FaceBody;       // Uint8Array | AsyncIterable<Uint8Array>
  isBase64: boolean;
}

FaceRenderResult

interface FaceRenderResult {
  status?: number;
  headers?: FaceResponseHeaders;
  cookies?: string[];
  lang?: string;
  htmlAttrs?: FaceAttributes;
  bodyAttrs?: FaceAttributes;
  head?: FaceHead;
  headTags?: FaceHeadTag[];
  styleTags?: FaceStyleTag[];
  csp?: FaceCspPolicy;
  html: string | AsyncIterable<Uint8Array>;
  hydration?: FaceHydration;
}

FaceHead and FaceHeadTag

interface FaceHead {
  title?: string;
  html?: string;  // legacy escaped head text, not raw HTML
}

type FaceHeadTag =
  | { type: 'title'; text: string }
  | { type: 'meta'; attrs: FaceAttributes }
  | { type: 'link'; attrs: FaceAttributes }
  | { type: 'script'; attrs: FaceAttributes; body?: string }
  | { type: 'style'; cssText: string; attrs?: FaceAttributes }
  | { type: 'raw'; html: string };

FaceCspPolicy

interface FaceCspPolicy {
  inlineScripts?: boolean;
  inlineStyles?: boolean;
  rawHead?: boolean;
}

Set any of these to false to disable that emission channel — the strict CSP path uses { inlineScripts: false, inlineStyles: false, rawHead: false }.

FaceHydration

type FaceHydration = FaceInlineHydration | FaceExternalHydration;

interface FaceInlineHydration {
  type?: 'inline';
  data: unknown;
  bootstrapModule: string;
}

interface FaceExternalHydration {
  type: 'external';
  data: unknown;
  dataUrl: string;
  bootstrapModule: string;
}

createFaceApp

function createFaceApp(options: FaceAppOptions): FaceApp;

interface FaceAppOptions {
  faces: FaceModule[];
  resources?: FaceResourceRoute[];
  isr?: FaceIsrOptions;
  ssrHydrationSidecars?: FaceSsrHydrationSidecarOptions;
  observability?: FaceObservabilityHooks;
  strictCsp?: FaceStrictCspOptions;
}

The returned FaceApp exposes handle(request: FaceRequest): Promise<FaceResponse>.

Lambda Function URL handlers

function createLambdaUrlStreamingHandler(
  options: { app: FaceRequestHandler; awslambda?: AwsLambdaGlobalLike },
): (event: LambdaUrlEvent, context: unknown) => Promise<void>;

function handleLambdaUrlEvent(
  app: FaceRequestHandler,
  event: LambdaUrlEvent,
): Promise<LambdaUrlResult>;

createLambdaUrlStreamingHandler is the production entry — it expects awslambda.streamifyResponse at runtime. handleLambdaUrlEvent is the unit-test entry — it accepts a synthesized event and returns what the handler would emit.