nuxt/dist/runtime/server/renderer/runtime.d.ts

Nuxt is a free and open-source framework with an intuitive and extendable way to create type-safe, performant and production-grade full-stack web applications and websites with Vue.js.

import { DevErrorObserveOptions, DevErrorReport } from "../dev-error/index.js";
import { NuxtServerRendererHooks, ServerHookable } from "../../../server/hooks.js";
import { NuxtRequestEvent, RequestEvent } from "@nuxt/schema";
import { NuxtSSRContext } from "#app/types";
//#region src/runtime/server/renderer/runtime.d.ts
/**
 * The request event the renderer reads. A server runtime whose own event has another
 * shape passes a web-standard view of it and names its own event in `~app`.
 */
export interface RendererEvent extends RequestEvent {
  /**
   * The runtime's own event, where it is not web-shaped.
   *
   * Prefixed, because a server runtime's own event may carry an `app` of its own (h3 v2's
   * event does), and read only through {@link appEvent}.
   */
  '~app'?: NuxtRequestEvent;
}
/** The event to pass to application code and to the render hooks. */
export declare function appEvent(event: RendererEvent): NuxtRequestEvent;
/**
 * A response the renderer has assembled but not yet handed to a platform `Response`:
 * the shape `ssrContext['~renderResponse']` and the payload cache are described in.
 */
export interface RenderedResponse {
  body?: unknown;
  statusCode?: number;
  statusMessage?: string;
  headers?: Record<string, string>;
}
/** A response the renderer stored while prerendering, keyed by payload URL. */
export interface CachedResponse extends RenderedResponse {
  body: string;
}
/** The route rules the renderer reads, as resolved by the server runtime for a request. */
export interface RendererRouteRules {
  /** Whether to server-render the route. */
  ssr?: boolean;
  streaming?: boolean;
  noScripts?: boolean;
  prerender?: boolean;
  redirect?: unknown;
  isr?: number | boolean | object;
  cache?: false | {
    maxAge?: number;
  };
}
/** Hooks the renderer calls while rendering a route. */
export type RendererHooks = Pick<ServerHookable<NuxtServerRendererHooks>, 'callHook'>;
/** Storage for the payloads rendered alongside a prerendered route. */
export interface PayloadCache {
  hasItem(key: string): Promise<boolean> | boolean;
  getItem(key: string): Promise<CachedResponse | null | undefined> | CachedResponse | null | undefined;
  setItem(key: string, value: CachedResponse): Promise<unknown> | unknown;
}
/** Capabilities the server runtime provides to the renderer for each build. */
export interface NuxtRendererOptions {
  /** Resolved runtime config. The event is passed for a runtime that resolves it per request. */
  runtimeConfig: (event: RendererEvent) => NuxtSSRContext['runtimeConfig'];
  /** URL of a file emitted into the build assets directory. */
  buildAssetsURL: (...path: string[]) => string;
  /** URL of a file served from the public directory. */
  publicAssetsURL: (...path: string[]) => string;
  /** Route rules matched for a request, with any base URL applied by the caller. */
  getRouteRules: (event: RendererEvent) => RendererRouteRules;
  /** Hooks the surrounding server runtime exposes to modules. */
  hooks: () => RendererHooks;
  /** Response constructor, so a runtime can provide a faster implementation than the platform's `Response`. */
  createResponse: (body: BodyInit | null, init?: ResponseInit) => Response;
  /** Error carrying an HTTP status, thrown for requests the renderer refuses. */
  createError: (init: {
    status: number;
    statusText?: string;
    data?: unknown;
    headers?: Record<string, string>;
  }) => Error;
  /** Send `103 Early Hints`, when the runtime supports them. */
  writeEarlyHints?: (event: RendererEvent, hints: {
    link: string;
  }) => void;
  /** Render an island request, when the runtime serves islands. */
  renderIsland?: (event: RendererEvent) => Promise<Response> | Response;
  /** Dev-only: called once a route has rendered without an error. */
  onRenderSuccess?: (event: RendererEvent) => void;
  /**
   * Report an error to the server runtime, so it logs it and fires whatever error hooks it owns.
   * Called once per error the renderer catches.
   */
  captureError?: (error: unknown, context: {
    event: RendererEvent;
    tags?: string[];
  }) => void | Promise<void>;
  /**
   * Dev-only: publish an error to the builder's live error channel and print it, returning the
   * report to show as an overlay or as a page. Resolves to `undefined` for an expected error,
   * or when the builder has no channel open.
   */
  onDevError?: (error: unknown, event: RendererEvent, options?: DevErrorObserveOptions) => Promise<DevErrorReport | undefined>;
  /** Prerender-only capabilities, absent from a runtime build. */
  prerender?: {
    payloadCache: PayloadCache;
    sharedDataCache?: NuxtSSRContext['~sharedPrerenderCache'];
    /** Wrap a render so the runtime can track the URLs in flight. */
    wrapRender?: <T>(event: RendererEvent, render: () => Promise<T>) => Promise<T>;
  };
}
/** Per-request Nuxt state the renderer reads from the request event, populated by the server runtime. */
export interface NuxtRequestState {
  'noSSR'?: boolean;
  /** Routes the render asked the server runtime to prerender as well, as raw paths. */
  'prerenderRoutes'?: string[];
  /** Set by the runtime for a request it made to itself, which may reach internal routes. */
  '~internal'?: boolean;
  /** Set when the runtime re-enters the renderer to render an error page. */
  '~rendering-error'?: boolean;
  /** Dev-only: CSS module URLs the builder has loaded for this request. */
  '~devClientCss'?: string[];
  /** Dev-only: serialized cause of the error being rendered. */
  '~error-cause'?: unknown;
}
export declare function getRequestState(event: RendererEvent): NuxtRequestState | undefined;
/**
 * Ask the server runtime to prerender `paths` alongside the route being rendered. What the
 * runtime does with them is its own concern; a runtime that does not prerender ignores them.
 */
export declare function addPrerenderRoutes(event: RendererEvent, ...paths: string[]): void;
//#endregion