astro/dist/core/app/base.d.ts

Astro is a modern site builder with web best practices, performance, and DX front-of-mind.

import type { RoutesList } from '../../types/astro.js';
import type { RemotePattern, RouteData } from '../../types/public/index.js';
import { getSetCookiesFromResponse } from '../cookies/index.js';
import { AstroIntegrationLogger, type AstroLogger } from '../logger/core.js';
import type { FetchHandler } from '../fetch/types.js';
import { type ErrorHandler } from '../errors/handler.js';
import type { WaitUntilHook } from '../wait-until.js';
import type { SSRManifest } from './types.js';
export interface DevMatch {
    routeData: RouteData;
    resolvedPathname: string;
}
export interface RenderOptions {
    /**
     * Whether to automatically add all cookies written by `Astro.cookie.set()` to the response headers.
     *
     * When set to `true`, they will be added to the `Set-Cookie` header as comma-separated key=value pairs. You can use the standard `response.headers.getSetCookie()` API to read them individually.
     *
     * When set to `false`, the cookies will only be available from `App.getSetCookieFromResponse(response)`.
     *
     * @default {false}
     */
    addCookieHeader?: boolean;
    /**
     * The client IP address that will be made available as `Astro.clientAddress` in pages, and as `ctx.clientAddress` in API routes and middleware.
     *
     * Default: `request[Symbol.for("astro.clientAddress")]`
     */
    clientAddress?: string;
    /**
     * The mutable object that will be made available as `Astro.locals` in pages, and as `ctx.locals` in API routes and middleware.
     */
    locals?: object;
    /**
     * A custom fetch function for retrieving prerendered pages - 404 or 500.
     *
     * If not provided, Astro will fall back to its default behavior for fetching error pages.
     *
     * When a dynamic route is matched but ultimately results in a 404, this function will be used
     * to fetch the prerendered 404 page if available. Similarly, it may be used to fetch a
     * prerendered 500 error page when necessary.
     *
     * @param {ErrorPagePath} url - The URL of the prerendered 404 or 500 error page to fetch.
     * @returns {Promise<Response>} A promise resolving to the prerendered response.
     */
    prerenderedErrorPageFetch?: (url: ErrorPagePath) => Promise<Response>;
    /**
     * Optional platform hook to keep background work alive after the response is sent.
     *
     * Adapters can pass this through so runtime cache providers can schedule cache writes
     * without blocking the response path.
     */
    waitUntil?: WaitUntilHook;
    /**
     * **Advanced API**: you probably do not need to use this.
     *
     * Default: `app.match(request)`
     */
    routeData?: RouteData;
}
type RequiredRenderOptions = Required<RenderOptions>;
export interface ResolvedRenderOptions {
    addCookieHeader: RequiredRenderOptions['addCookieHeader'];
    clientAddress: RequiredRenderOptions['clientAddress'] | undefined;
    prerenderedErrorPageFetch: RequiredRenderOptions['prerenderedErrorPageFetch'] | undefined;
    locals: RequiredRenderOptions['locals'] | undefined;
    routeData: RequiredRenderOptions['routeData'] | undefined;
    waitUntil: RequiredRenderOptions['waitUntil'] | undefined;
}
export interface RenderErrorOptions extends ResolvedRenderOptions {
    response?: Response;
    status: 404 | 500;
    /**
     * Whether to skip middleware while rendering the error page. Defaults to false.
     */
    skipMiddleware?: boolean;
    /**
     * Allows passing an error to 500.astro. It will be available through `Astro.props.error`.
     */
    error?: unknown;
    /**
     * The pathname to use for the error page render context. If omitted, the
     * error handler computes it from `request` via a short-lived `FetchState`.
     */
    pathname?: string;
}
type ErrorPagePath = `${string}/404` | `${string}/500` | `${string}/404/` | `${string}/500/` | `${string}/404/index.html` | `${string}/500/index.html` | `${string}404.html` | `${string}500.html`;
export declare abstract class BaseApp {
    #private;
    manifest: SSRManifest;
    baseWithoutTrailingSlash: string;
    get logger(): AstroLogger;
    /**
     * Route data derived from the manifest, used for route matching. Reads and
     * writes go through the single per-manifest route table, so HMR updates are
     * visible to every consumer at once.
     */
    get manifestData(): {
        routes: RouteData[];
    };
    set manifestData(routesList: {
        routes: RouteData[];
    });
    get adapterLogger(): AstroIntegrationLogger;
    constructor(manifest: SSRManifest, streaming?: boolean);
    /**
     * Resolves the user-configured logger destination from the manifest and
     * returns the logger. Lazy and only resolves once; safe to call before
     * the first render (adapters use this to log startup messages through
     * the configured destination).
     */
    getLogger(): Promise<AstroLogger>;
    /**
     * The streaming flag fed into the internal `FetchState` facade hooks on
     * the fast path. Returns the constructor flag by
     * default; `BuildApp` overrides this to return `undefined` so streaming
     * falls through to the environment default (`manifest.serverLike`).
     */
    protected resolveStreaming(): boolean | undefined;
    /**
     * Override the fetch handler used to dispatch requests. Entrypoints
     * call this with the default export of `virtual:astro:fetchable` to
     * plug in a user-authored handler from `src/fetch.ts`.
     */
    setFetchHandler(handler: {
        fetch: FetchHandler;
    }): void;
    /**
     * Returns the error handler used by this app. The default is a thin
     * bridge over the functional error API — strategy selection (production
     * default / dev / build) is environment-driven inside `renderErrorPage`.
     * External subclasses can override this to customize error rendering.
     */
    protected createErrorHandler(): ErrorHandler;
    abstract isDev(): boolean;
    /**
     * Resets the cached adapter logger so it picks up a new logger instance.
     * Used by BuildApp when the logger is replaced via setOptions().
     */
    protected resetAdapterLogger(): void;
    getAllowedDomains(): Partial<RemotePattern>[] | undefined;
    protected matchesAllowedDomains(forwardedHost: string, protocol?: string): boolean;
    static validateForwardedHost(forwardedHost: string, allowedDomains?: Partial<RemotePattern>[], protocol?: string): boolean;
    set setManifestData(newManifestData: RoutesList);
    removeBase(pathname: string): string;
    /**
     * Fully decodes a pathname, falling back to a single decode and then the raw pathname
     * when validation fails. Adapter matching runs before `render()`, so it must not throw
     * for request input that render-time validation handles.
     */
    private safeDecodePathname;
    /**
     * Extracts the base-stripped, decoded pathname from a request.
     * Used by adapters to compute the pathname for dev-mode route matching.
     */
    getPathnameFromRequest(request: Request): string;
    /**
     * Given a `Request`, it returns the `RouteData` that matches its `pathname`. By default, prerendered
     * routes aren't returned, even if they are matched.
     *
     * When `allowPrerenderedRoutes` is `true`, the function returns matched prerendered routes too.
     * @param request
     * @param allowPrerenderedRoutes
     */
    match(request: Request, allowPrerenderedRoutes?: boolean): RouteData | undefined;
    /**
     * A matching route function to use in the development server.
     * Contrary to the `.match` function, this function resolves props and params, returning the correct
     * route based on the priority, segments. It also returns the correct, resolved pathname.
     * @param pathname
     */
    devMatch(pathname?: string): Promise<DevMatch | undefined> | undefined;
    private computePathnameFromDomain;
    render(request: Request, { addCookieHeader, clientAddress, locals, prerenderedErrorPageFetch, routeData, waitUntil, }?: RenderOptions): Promise<Response>;
    setCookieHeaders(response: Response): Generator<string, string[], any>;
    /**
     * Reads all the cookies written by `Astro.cookie.set()` onto the passed response.
     * For example,
     * ```ts
     * for (const cookie_ of App.getSetCookieFromResponse(response)) {
     *     const cookie: string = cookie_
     * }
     * ```
     * @param response The response to read cookies from.
     * @returns An iterator that yields key-value pairs as equal-sign-separated strings.
     */
    static getSetCookieFromResponse: typeof getSetCookiesFromResponse;
    /**
     * If it is a known error code, try sending the according page (e.g. 404.astro / 500.astro).
     * This also handles pre-rendered /404 or /500 routes.
     *
     * Delegates to the app's configured `ErrorHandler`. To customize behavior
     * for a specific environment, override `createErrorHandler()` rather than
     * this method.
     */
    renderError(request: Request, options: RenderErrorOptions): Promise<Response>;
    getDefaultStatusCode(routeData: RouteData, pathname: string): number;
    getManifest(): SSRManifest;
    logThisRequest({ pathname, method, statusCode, isRewrite, timeStart, }: {
        pathname: string;
        method: string;
        statusCode: number;
        isRewrite: boolean;
        timeStart: number;
    }): void;
    abstract logRequest(_options: LogRequestPayload): void;
}
export type LogRequestPayload = {
    /**
     * The current path being rendered
     */
    pathname: string;
    /**
     * The method of the request
     */
    method: string;
    /**
     * The status code of the request
     */
    statusCode: number;
    /**
     * If the current request is a rewrite
     */
    isRewrite: boolean;
    /**
     * How long it took to render the request
     */
    reqTime: number;
};
export {};