@qwik.dev/core/dist/server.d.ts

An open source framework for building instant loading web apps at any scale, without the extra effort.

/// <reference path="./server-modules.d.ts" />

import type { QwikManifest } from './optimizer';
import { ResolvedManifest } from './optimizer';
import type { ServerQwikManifest } from './optimizer';
import type { SnapshotResult } from '.';
import type { StreamWriter } from './internal';
import type { SymbolMapperFn } from './optimizer';

/** @public */
declare interface DevJSX {
    fileName: string;
    lineNumber: number;
    columnNumber: number;
    stack?: string;
}

/**
 * Any function taking a props object that returns JSXOutput.
 *
 * The `key`, `flags` and `dev` parameters are for internal use.
 *
 * @public
 */
declare type FunctionComponent<P = unknown> = {
    renderFn(props: P, key: string | null, flags: number, dev?: DevJSX): JSXOutput;
}['renderFn'];

/**
 * Provides the `backpatch-executor.js` executor script as a string.
 *
 * @public
 */
export declare function getQwikBackpatchExecutorScript(opts?: {
    debug?: boolean;
}): string;

/**
 * Provides the `qwikloader.js` file as a string. Useful for tooling to inline the qwikloader script
 * into HTML.
 *
 * @public
 */
export declare function getQwikLoaderScript(opts?: {
    debug?: boolean;
}): string;

/**
 * Provides the `qwik-prefetch-service-worker.js` file as a string. Useful for tooling to inline the
 * qwik-prefetch-service-worker script into HTML.
 *
 * @public
 */
export declare function getQwikPrefetchWorkerScript(opts?: {
    debug?: boolean;
}): string;

/** @public */
export declare interface InOrderAuto {
    strategy: 'auto';
    maximumInitialChunk?: number;
    maximumChunk?: number;
}

/** @public */
declare interface InOrderDirect {
    strategy: 'direct';
}

/** @public */
export declare interface InOrderDisabled {
    strategy: 'disabled';
}

/** @public */
export declare type InOrderStreaming = InOrderAuto | InOrderDisabled | InOrderDirect;

/** @public */
declare type JSXChildren = string | number | boolean | null | undefined | Function | RegExp | JSXChildren[] | Promise<JSXChildren> | Signal<JSXChildren> | JSXNode;

/**
 * A JSX Node, an internal structure. You probably want to use `JSXOutput` instead.
 *
 * @public
 */
declare interface JSXNode<T extends string | FunctionComponent | unknown = unknown> {
    type: T;
    props: T extends FunctionComponent<infer P> ? P : Record<any, unknown>;
    children: JSXChildren | null;
    key: string | null;
    dev?: DevJSX;
}

/**
 * Any valid output for a component
 *
 * @public
 */
declare type JSXOutput = JSXNode | string | number | boolean | null | undefined | JSXOutput[];

/** @public */
export declare type OutOfOrderStreaming = boolean;

/** @public */
export declare interface PrefetchResource {
    url: string;
    imports: PrefetchResource[];
}

/** @public */
export declare interface PreloaderOptions {
    /**
     * Maximum number of preload links to add during SSR. These instruct the browser to preload likely
     * bundles before the preloader script is active. This most likely includes the core and the
     * preloader script itself. Setting this to 0 will disable all preload links.
     *
     * Preload links can delay LCP, which is a Core Web Vital, but it can increase TTI, which is not a
     * Core Web Vital but more noticeable to the user.
     *
     * Defaults to `5`
     */
    ssrPreloads?: number;
    /**
     * Maximum number of simultaneous preload links that the preloader will maintain. If you set this
     * higher, the browser will have all JS files in memory sooner, but it will contend with other
     * resource downloads. Furthermore, if a bundle suddenly becomes more likely, it will have to wait
     * longer to be preloaded.
     *
     * Bundles that reach 100% probability (static imports of other bundles) will always be preloaded
     * immediately, no limit.
     *
     * Defaults to `25`
     */
    maxIdlePreloads?: number;
}

/** @public */
export declare type QwikLoaderOptions = 'module' | 'inline' | 'never' | {
    /** @deprecated No longer used. */
    include?: 'always' | 'never' | 'auto';
    /** @deprecated No longer used. */
    position?: 'top' | 'bottom';
};

/** @public */
export declare type Render = RenderToString | RenderToStream;

/** @public */
export declare interface RenderOptions extends SerializeDocumentOptions {
    /** Defaults to `true` */
    snapshot?: boolean;
    /**
     * Specifies the root of the JS files of the client build. Setting a base, will cause the render
     * of the `q:base` attribute in the `q:container` element.
     */
    base?: string | ((options: RenderOptions) => string);
    /** Language to use when rendering the document. */
    locale?: string | ((options: RenderOptions) => string);
    /**
     * Specifies how the Qwik Loader is included in the document. This enables interactivity and lazy
     * loading.
     *
     * `module`: Use a `<script>` tag to load the Qwik Loader. Subsequent page loads will have the
     * script cached and instantly running.
     *
     * `inline`: This embeds the Qwik Loader script directly in the document. This adds about 3kB
     * before compression, which typically is reduced to about 1.6kB with gzip.
     *
     * `never`: Do not include the Qwik Loader script. This is mostly useful when embedding multiple
     * containers on the same page.
     *
     * Defaults to `module`.
     *
     * Note that the Qwik Loader is absolutely required for Qwik to work. There must be an instance of
     * it loaded for any interactivity to happen.
     */
    qwikLoader?: QwikLoaderOptions;
    /** Specifies how preloading is handled. This ensures that code is instantly available when needed. */
    preloader?: PreloaderOptions | false;
    /**
     * When set, the app is serialized into a fragment. And the returned html is not a complete
     * document. Defaults to `html`
     */
    containerTagName?: string;
    containerAttributes?: Record<string, string>;
    /** Metadata that can be retrieved during SSR with `useServerData()`. */
    serverData?: Record<string, any>;
}

/** @public */
export declare interface RenderResult {
    /** @deprecated Not longer used in v2 */
    snapshotResult?: SnapshotResult | undefined;
    isStatic: boolean;
    manifest?: ServerQwikManifest;
}

/** @public */
export declare type RenderToStream = (opts: RenderToStreamOptions) => Promise<RenderToStreamResult>;

/**
 * Creates a server-side `document`, renders to root node to the document, then serializes the
 * document to a string.
 *
 * @public
 */
export declare const renderToStream: (jsx: JSXOutput, opts: RenderToStreamOptions) => Promise<RenderToStreamResult>;

/** @public */
export declare interface RenderToStreamOptions extends RenderOptions {
    stream: StreamWriter;
    streaming?: StreamingOptions;
}

/** @public */
export declare interface RenderToStreamResult extends RenderResult {
    flushes: number;
    size: number;
    timing: {
        firstFlush: number;
        render: number;
        snapshot: number;
    };
}

/** @public */
export declare type RenderToString = (opts: RenderToStringOptions) => Promise<RenderToStringResult>;

/**
 * Creates a server-side `document`, renders to root node to the document, then serializes the
 * document to a string.
 *
 * @public
 */
export declare const renderToString: (jsx: JSXOutput, opts?: RenderToStringOptions) => Promise<RenderToStringResult>;

/** @public */
export declare interface RenderToStringOptions extends RenderOptions {
}

/** @public */
export declare interface RenderToStringResult extends RenderResult {
    html: string;
    timing: {
        firstFlush: number;
        render: number;
        snapshot: number;
    };
}

/**
 * Merges a given manifest with the built manifest and provides mappings for symbols.
 *
 * @public
 */
export declare function resolveManifest(manifest?: Partial<QwikManifest | ResolvedManifest> | undefined): ResolvedManifest | undefined;

/** @public */
export declare interface SerializeDocumentOptions {
    manifest?: Partial<QwikManifest | ResolvedManifest>;
    symbolMapper?: SymbolMapperFn;
    debug?: boolean;
}

/** @public */
export declare function setServerPlatform(manifest?: Partial<QwikManifest | ResolvedManifest>): Promise<void>;

/**
 * A signal is a reactive value which can be read and written. When the signal is written, all tasks
 * which are tracking the signal will be re-run and all components that read the signal will be
 * re-rendered.
 *
 * Furthermore, when a signal value is passed as a prop to a component, the optimizer will
 * automatically forward the signal. This means that `return <div title={signal.value}>hi</div>`
 * will update the `title` attribute when the signal changes without having to re-render the
 * component.
 *
 * @public
 */
declare interface Signal<T = any> {
    /** Reading from this subscribes to updates; writing to this triggers updates. */
    value: T;
    /** Reading from this does not subscribe to updates; writing to this does not trigger updates. */
    untrackedValue: T;
    /**
     * Use this to trigger running subscribers, for example when the value mutated but remained the
     * same object.
     */
    trigger(): void;
}

/** @public */
export declare interface StreamingOptions {
    inOrder?: InOrderStreaming;
    outOfOrder?: OutOfOrderStreaming;
}

/** @public */
export declare const versions: {
    readonly qwik: string;
    readonly qwikDom: string;
};

export { }