createHandler

createHandler creates the handler used by the server entry.

Import

import { createHandler } from "@solidjs/start/server";

Type

type HandlerOptions = {
  mode?: "sync" | "async" | "stream";
  nonce?: string;
  renderId?: string;
  onCompleteAll?: (options: { write: (value: any) => void }) => void;
  onCompleteShell?: (options: { write: (value: any) => void }) => void;
};

function createHandler(
  fn: (context: PageEvent) => JSX.Element,
  options?:
    | HandlerOptions
    | ((context: PageEvent) => HandlerOptions | Promise<HandlerOptions>),
  routerLoad?: (event: FetchEvent) => Promise<void>
): StartHandler;

Parameters

fn

• Type: (context: PageEvent) => JSX.Element
• Required: Yes

Function that returns the server-rendered document.

options

• Type: HandlerOptions | ((context: PageEvent) => HandlerOptions | Promise<HandlerOptions>)
• Default: {}
• Required: No

Rendering options or a function that returns rendering options.

The options object supports these fields:

routerLoad

• Type: (event: FetchEvent) => Promise<void>
• Required: No

Optional setup function for a custom router. SolidStart calls it before creating the page event and rendering the route. Router integrations such as TanStack Router can use it to load their server-side routing state.

Return value

• Type: StartHandler

Returns the H3 application used by the server entry. StartHandler extends H3's H3 type while keeping generated declaration files portable.

Behavior

• Creates a page event for matched UI routes.
• Matching API routes run before page rendering. For HEAD requests, the route HEAD export is used, with fallback to GET.
• Synchronous mode and disabled SSR render with renderToString and return the HTML string.
• Async mode returns the renderToStream result.
• Stream mode is the default and returns a readable stream.
• If page rendering sets a Location response header, the handler sends or writes a redirect response depending on the render phase.

Examples

Basic usage

import { createHandler, StartServer } from "@solidjs/start/server";

export default createHandler((event) => <StartServer document={Document} />);

Related

• StartServer